Git worktrees, explained

What is a git worktree?

Every repository starts with one working directory. git worktree add attaches more. Each worktree is a real directory with real files and its own checked-out branch, and all of them share the same repository underneath: one object database, one set of branches and tags, one stash list. Commit in one worktree and the commit is immediately visible in the others.

A linked worktree is cheap because it holds no second copy of the repository. Its .git is a plain file pointing back at .git/worktrees/<name> in the main checkout. That is also why git always knows which worktrees exist: git worktree list reads those records, and git worktree prune deletes stale ones.

The classic uses: fix an urgent bug on main while a feature branch sits mid-refactor in your main checkout, run a long test suite on one branch while you edit another, or check out a colleague's branch next to yours to review it. The newer use is coding agents, which create worktrees so several sessions can run in parallel without touching your checkout.

Worktree vs branch

A branch is a line of history; a worktree is a place on disk where a branch is checked out. Switching branches reuses one directory and one set of build artifacts, and asks you to stash or commit first. A worktree gives the second branch its own directory, so both exist at once, each with its own editor window, dev server or test run. Switch branches for quick hops; add a worktree when both branches need to be running at the same time.

Worktree vs a second clone

A second git clone also gives you a second directory, but it duplicates the entire object database, fetches independently, and its branches drift from your first clone's. A worktree shares everything: it costs almost no disk, needs no extra fetching, and a commit made in one worktree is immediately on the shared repository. The only things a clone isolates that a worktree doesn't are the config and the remotes, and that's rarely what you want isolated.

How to use git worktree: add, list, remove, prune

Everything is a subcommand of git worktree. The path you pass is where the new directory is created; sibling directories keep things tidy.

remove refuses if the worktree has uncommitted changes; add --force to discard them. prune only deletes stale bookkeeping, never files. Two subcommands you'll want eventually: git worktree lock keeps a worktree on a removable drive from being pruned while it's unmounted, and git worktree repair fixes the back-references after you move the main repository itself.

How to remove or delete a git worktree

Delete a worktree with git worktree remove, not rm -rf. One command deletes the directory and the repository's record of it. You can run it from any worktree of the repository, including the one you're removing.

Three messages stop a removal. Each one names its fix:

• fatal: '../repo-review' contains modified or untracked files, use --force to delete it. To keep that work, commit it or run git stash in that worktree first. The stash list is shared, so you can apply the stash from any other worktree. To throw the work away, add --force.
• fatal: cannot remove a locked working tree. Someone ran git worktree lock on it. Run git worktree unlock ../repo-review first, or pass --force twice (-f -f).
• fatal: '.' is a main working tree. Only linked worktrees can be removed. The main worktree is the repository itself.

Removing a worktree never deletes its branch. git branch -d deletes the branch once it's merged; git branch -D deletes it regardless. Delete the branch after the worktree, not before: git refuses to delete a branch that a worktree still has checked out.

Cheat sheet

The two errors everyone hits

fatal: 'branch' is already used by worktree at '...'

Git refuses to check out a branch that is already checked out in another worktree, because two working directories editing one branch would silently overwrite each other's view of it. Either go work in the worktree that already has the branch (git worktree list shows where it is), remove that worktree if it's stale, or take a new branch instead: git worktree add -b branch-2 ../dir branch.

error: cannot delete branch 'x' used by worktree at '...'

The mirror image: a branch cannot be deleted while any worktree has it checked out, and -D does not override it. Remove the worktree first (git worktree remove ../dir, or git worktree prune if the directory is already gone), then delete the branch.

Keeping worktrees tidy

• Keep worktrees as siblings of the main checkout (repo/, repo-review/), never nested inside it. A worktree inside another worktree shows up as untracked files.
• Name the directory after the task rather than the branch. The branch name is visible in git worktree list anyway.
• Treat worktrees like branches: create them freely, remove them when the work merges.
• Each worktree has its own untracked files, so each needs its own node_modules or build directory. That isolation is usually the point.
• If you rm -rf a worktree directory instead of removing it properly, run git worktree prune so the repository's records match the disk.

Worktrees and coding agents

Worktrees stopped being a power-user trick when coding agents adopted them. Claude Code can run whole sessions and subagents in isolated worktrees, the Codex app and Cursor's agents run in worktrees of their own, and opencode runs parallel sessions the same way. In each case the agent gets a private working directory, works in parallel, and leaves a branch behind. Your job is to read what it did before it merges. The workflow, per tool, is in Claude Code worktrees, explained.

Which Git GUIs support worktrees?

Support varies more between Git GUIs than any other mainstream feature:

Kris is the founder of Meridian and spends most days in the workflow these guides cover: worktrees, diffs, and reading what the agents wrote.