Git, branches & worktrees

Think of git as a time machine for your project. Every time meaningful work happens, it quietly records a snapshot called a commit, like a save point in a video game. And because every save point is kept forever, you can always rewind to an earlier version, line up two versions side by side, or undo a change you didn't love. Hold onto one magic word: reversible. Nothing is permanent until you say so.

The best part? Sparkle drives all of this for you. You won't type a single git command. You just get the safety net underneath everything you do. If you ever want the gentle, friendly backstory, GitHub's About Git is a calm place to start. But you don't need it to begin, and you don't need it to be brave.

You know the panic: an AI confidently rewrites half your project, sounds proud of itself, and leaves you with no way back. git is the cure. Every meaningful change is a commit, a save point you can snap back to, so "the agent broke it" stops being a crisis and becomes a one-click rewind. And Sparkle commits agent work incrementally, which is the whole trick: your history stays granular. You're never unwinding one giant mystery blob, you're stepping back one clean change at a time.

git is distributed version control: snapshots of content addressed by SHA, each commit pointing at its parent(s). You know this. The thing worth noticing is that Sparkle commits agent output incrementally, so history stays fine-grained and every change is independently revertible. There's no new model to learn here. It's the same object graph you already reason about, just driven from the UI instead of your shell.

A branch is like hitting "Save As…" before you start tinkering. The agent works on its own copy, so your main project just sits there, untouched, exactly as it was, the entire time. Don't like the result? Throw the branch away and it's as if it never happened. Nothing breaks, nothing is at risk, and you are the one who decides when (or if) those changes ever come back into your main version, which is called a merge.

Sparkle makes a fresh branch for every agent task automatically, so experimenting is always free and always safe. Go ahead and be reckless with your ideas. Atlassian has a friendly walkthrough if you're curious: Using branches.

Branches are where the "undo a bad agent run cleanly" magic actually lives. Because Sparkle hands every agent task its own branch, a run that goes sideways is fully sealed off: your main line never saw it, so you just delete the branch and move on. No surgery, no cleanup, no regret. Burn this mental model into your head, because it's the one that keeps you out of trouble: never edit the one precious copy. Branch first, judge the result, then merge only the good stuff.

A branch is a named, movable pointer to a line of commits diverging from main. Sparkle spins one up per agent task, so parallel work and throwaway experiments stay isolated until you merge (or discard). The canonical reference is still Branches in a Nutshell.

Talk is cheap. Show me the code.

Picture two helpers trying to edit the same document on the same desk at once. They'd bump elbows, talk over each other, and overwrite each other's work. A worktree fixes that by giving each agent its own desk: same project, but a workspace entirely its own. That's how Sparkle runs several agents at once and keeps everyone's work clean and separate. And yes, as always, you don't set any of this up. Sparkle just quietly hands each agent its own room.

Here's the distinction that pays off: branches isolate history, worktrees isolate the files on disk. Without them, two agents on two branches would still brawl over the same working directory. Sparkle gives each agent its own worktree, so you can fan out multiple agents and trust that not one of them is stepping on another's files. That isolation is exactly what makes a bad run disposable: it lived in its own workspace, so deleting it never so much as grazes the others.

A worktree is a checked-out branch in its own working directory, sharing the one object store. Sparkle assigns one per agent, so N agents run concurrently with zero contention over the index or working tree. No stashing, no checkout thrash, none of the context-switch tax you've paid a thousand times. See git-worktree.

There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies.