One Archive, Many Desks

a second working folder on the SAME repository - no stash juggling, no second clone

the half-written feature - open on your desk, not ready to seal

The situation every developer knows: an urgent fix arrives mid-feature.

Your desk is covered in half-written work. The old moves both hurt: stash and switch packs your desk into a drawer and breaks your flow; a second clone is a whole separate repository - separate history, separate fetches, double the disk. What you actually want is a SECOND DESK that reads the SAME archive. (Archive = the repository - git's own word for it.)

$ git worktree add ../logo-desk -b logo-redesign
Preparing worktree (new branch 'logo-redesign')
HEAD is now at 9ded166 fix: salt the focaccia

a new desk, born on its own branch

One command opens the second desk.

git worktree add takes a path and a branch: git builds a NEW working folder at that path, checks the branch out there, and both folders share one repository underneath. Nothing is copied - the archive already has every object.

logo-desk/ - .git is a pointer

On disk: two folders, one archive.

The new desk looks like any project folder - files you can edit, a .git entry of its own. But look closely: in the MAIN desk, .git is a DIRECTORY (the archive itself). In the second desk, .git is a tiny FILE - one line pointing back into the shared archive. Every desk reads and writes the same archive.

$ git worktree list
.../work-m8/bakery     9ded166 [main]
.../work-m8/logo-desk  9ded166 [logo-redesign]

two desks, one archive, one commit - for now

The registry: every desk, its commit, its branch.

git worktree list is the desk registry. Both desks stand at the same commit right now - one history, two places to stand on it. Each desk has its OWN HEAD; switching branches on one never disturbs the other.

From the archive's point of view, nothing unusual happened.

The timeline does not know about desks. There is one graph; the two branches simply have a desk each standing on them. Work on either desk grows its own branch exactly as the Timelines chapter taught.

$ git switch logo-redesign   # from the MAIN desk
fatal: 'logo-redesign' is already used by
worktree at '.../logo-desk'

the sticker is on desk B - desk A may not grab it

The one law: a branch fits ONE desk at a time.

Two desks writing the same branch would fight over the same sticker - so git refuses. If you need the branch at another desk, release it first (switch away, or remove the desk). The refusal below is the guard working, not an error to fight.

$ git worktree remove ../logo-desk
$ git worktree add ../ghost-desk -b ghost
Preparing worktree (new branch 'ghost')
... (folder deleted by hand)
$ git worktree prune
$ git worktree list
.../work-m8/bakery  9ded166 [main]

desks come and go; the archive keeps everything sealed

Tidy teardown: remove the desk, keep the work.

git worktree remove folds the desk away - the BRANCH and its commits stay in the archive; only the working folder goes. If a desk's folder was deleted by hand, git worktree prune clears the ghost registration. The registry ends clean.

When to reach for a worktree - the honest short list.

The urgent fix - hotfix on a clean desk while the feature desk stays exactly as you left it.

The long review - check out a teammate's branch beside yours and compare with your editor, not your memory.

The heavy build - run tests on one desk while you keep typing on another.

One archive, many desks - the drawer stays for quick holds; the desk is for real parallel work.