Guide
git worktree cheat sheet: every command you actually need
git worktree lets one repository have several working directories, each on its own branch. It has been in git since 2.5 and most people learn it the week they start running agents in parallel.
Create
- git worktree add ../app-fix -b fix/login — new branch fix/login, checked out in ../app-fix.
- git worktree add ../app-review origin/feature — check out an existing branch (or any commit) in a new folder.
- git worktree add --detach ../app-scratch HEAD — a throwaway folder on a detached HEAD, no branch created.
- git worktree add -b spike ../app-spike main — branch from main, regardless of what the current folder has checked out.
Inspect
- git worktree list — every worktree, its path, commit and branch.
- git worktree list --porcelain — the same, in a format scripts can parse.
- git branch -vv — shows which branches are checked out in another worktree (marked with +).
Clean up
- git worktree remove ../app-fix — delete the folder and unregister it. Refuses if there are uncommitted changes.
- git worktree remove --force ../app-fix — the same, discarding those changes.
- git worktree prune — forget worktrees whose folders were deleted by hand.
- git branch -d fix/login — the branch outlives the worktree; delete it separately once merged.
Move and protect
- git worktree move ../app-fix ../archive/app-fix — relocate a worktree without breaking it.
- git worktree lock ../app-usb --reason "external drive" — stop prune from removing a worktree on a disconnected drive.
- git worktree unlock ../app-usb — undo it.
What is shared and what is not
Shared: commits, branches, tags, stashes, remotes and config — everything under the main .git directory. A commit made in one worktree is immediately visible from all the others.
Not shared: the files on disk, the index, and anything untracked or ignored — .env files, node_modules, virtualenvs, build output. Each worktree needs its own install and its own copy of local config.
One rule git enforces: a branch can be checked out in only one worktree at a time. That rule is what makes worktrees safe for parallel work, and it is the source of the most common error.
Questions
- Is a git worktree the same as a clone?
- No. A clone copies the whole repository. A worktree is another working directory on the same repository, so it is created instantly and shares history, branches and stashes.
- Where should worktrees live?
- Next to the main checkout (../app-task) or in a dedicated folder outside the repository. Putting them inside the repository makes tools and file watchers index them twice.
- Why use worktrees for AI coding agents?
- Each agent gets its own files and branch, so parallel agents cannot overwrite each other, and each result is a normal branch you can diff and merge.