Reference · Git Worktree Cheat Sheet

The two facts everything follows from

1. All worktrees share one repository — every commit and branch is instantly visible from all of them. Only HEAD, the index, and the files on disk are per-worktree.
2. A branch can be checked out in only one worktree at a time.

Checked out ≠ merged. The one-worktree rule restricts checking out a branch, never merging it. You can merge an agent's branch into main while that agent's worktree still sits on it — the agent can even still be running. You never need to check out an agent's branch to land its work, which is precisely what makes this workflow safe.

Vocabulary

Term	Means
repository	The `.git` database: all commits, all branches. One per project, shared by every worktree.
working tree	One branch unpacked into real files you can edit. A view onto the repository.
main worktree	The working tree made by `git clone` / `git init`. Holds the real `.git` folder. Cannot be removed by `git worktree remove`.
linked worktree	Any working tree added by `git worktree add`. Its `.git` is a one-line file pointing back to the main repository.
HEAD	Per-worktree pointer naming the branch this directory is on. Answer to "which branch am I on here".
prunable	Git's label for worktree metadata whose directory has vanished. Cleared by `git worktree prune`.

Term

Means

repository

The .git database: all commits, all branches. One per project, shared by every worktree.

working tree

One branch unpacked into real files you can edit. A view onto the repository.

main worktree

The working tree made by git clone / git init. Holds the real .git folder. Cannot be removed by git worktree remove.

linked worktree

Any working tree added by git worktree add. Its .git is a one-line file pointing back to the main repository.

HEAD

Per-worktree pointer naming the branch this directory is on. Answer to "which branch am I on here".

prunable

Git's label for worktree metadata whose directory has vanished. Cleared by git worktree prune.

Commands

Command	Does
`git worktree add ../foo`	New worktree at `../foo` on a new branch named `foo` (after the folder), started from current `HEAD`.
`git worktree add ../foo -b fix`	New worktree on a new branch explicitly named `fix`. Refuses if `fix` already exists.
`git worktree add ../foo existing`	New worktree on the existing branch `existing`. Refuses if it is checked out elsewhere.
`git worktree list`	Every worktree, its commit, and its branch. Flags stale ones `prunable`.
`git worktree remove ../foo`	Deletes the directory and its metadata. Refuses if the tree is dirty. Leaves the branch alone.
`git worktree remove -f ../foo`	Same, discarding uncommitted changes. Check what you are throwing away first.
`git worktree prune`	Clears metadata for worktrees whose directories are already gone. The fix after an `rm -rf`.
`git worktree move ../foo ../bar`	Relocates a worktree, fixing its pointers. Never just `mv` one.
`git branch`	`` = checked out here. `+` = checked out in another* worktree.

Command

Does

git worktree add ../foo

New worktree at ../foo on a new branch named foo (after the folder), started from current HEAD.

git worktree add ../foo -b fix

New worktree on a new branch explicitly named fix. Refuses if fix already exists.

git worktree add ../foo existing

New worktree on the existing branch existing. Refuses if it is checked out elsewhere.

git worktree list

Every worktree, its commit, and its branch. Flags stale ones prunable.

git worktree remove ../foo

Deletes the directory and its metadata. Refuses if the tree is dirty. Leaves the branch alone.

git worktree remove -f ../foo

Same, discarding uncommitted changes. Check what you are throwing away first.

git worktree prune

Clears metadata for worktrees whose directories are already gone. The fix after an rm -rf.

git worktree move ../foo ../bar

Relocates a worktree, fixing its pointers. Never just mv one.

git branch

* = checked out here. + = checked out in another worktree.

The full lifecycle

# START — run from the main worktree git worktree add ../agent-alpha # WORK — the agent lives here; commit as normal cd ../agent-alpha # LAND — go back to the worktree that has main. no special command exists. cd ../app git branch --show-current # confirm "main" BEFORE merging git merge agent-alpha # TEAR DOWN — two separate things: the directory, then the branch git worktree remove ../agent-alpha git branch -d agent-alpha

Direction of merge

git merge X merges X into the branch of the directory you are standing in. Running git merge main from inside the agent's worktree does the reverse of landing. Standing in the wrong directory is the classic worktree mistake — git branch --show-current is the one-second guard.

When it goes wrong

Git says	Do this
`fatal: 'x' is already used by worktree at /path`	That branch is checked out elsewhere. Git names the path — go there, or pick another branch. Do not force.
`fatal: '../x' contains modified or untracked files, use --force to delete it`	Uncommitted work is in there. `cd` in, run `git status`, and decide: commit it, or `remove -f` to discard it.
`git worktree list` shows a path that no longer exists, marked `prunable`	Someone `rm -rf`'d a worktree. Run `git worktree prune`, then deal with the orphaned branch separately.
`error: cannot delete branch 'x' used by worktree at /path`	You tried to delete the branch before removing its worktree. This is why the order is remove worktree, then delete branch — never the reverse.
`error: the branch 'x' is not fully merged` (on `git branch -d`)	Real safety net: that branch has commits not on your current branch. Verify with `git log main..x` before `-D` discards them.

Git says

Do this

fatal: 'x' is already used by worktree at /path

That branch is checked out elsewhere. Git names the path — go there, or pick another branch. Do not force.

fatal: '../x' contains modified or untracked files, use --force to delete it

Uncommitted work is in there. cd in, run git status, and decide: commit it, or remove -f to discard it.

git worktree list shows a path that no longer exists, marked prunable

Someone rm -rf'd a worktree. Run git worktree prune, then deal with the orphaned branch separately.

error: cannot delete branch 'x' used by worktree at /path

You tried to delete the branch before removing its worktree. This is why the order is remove worktree, then delete branch — never the reverse.

error: the branch 'x' is not fully merged (on git branch -d)

Real safety net: that branch has commits not on your current branch. Verify with git log main..x before -D discards them.

Never rm -rf a worktree

It strands two things, not one: stale metadata (fixed by git worktree prune) and the branch, which survives silently and still holds any unmerged commits. git worktree remove handles the first properly; the branch is always your call.