teebe › Guides › Git worktree cheat sheet

Git worktree cheat sheet

Every git worktree command you need, plus the errors you'll actually hit.

A git worktree is a second working directory attached to the same repository: its own HEAD, index, and files, but the same .git object store, branches, stashes, and remotes as your main checkout. The one rule that trips people up: a branch can be checked out in only one worktree at a time. This is a straight command reference. For the difference between a worktree and a branch, see git worktree vs branch.

Create a worktree

New branch, off the current HEAD:

git worktree add -b feature-a ../repo-feature-a

Existing local branch:

git worktree add ../repo-feature-a feature-a

From a remote branch, fetch first so git can see it, then add it:

git fetch origin
git worktree add -b feature-a ../repo-feature-a origin/feature-a

Detached HEAD, no branch at all, useful for a quick look at a commit:

git worktree add --detach ../repo-scratch abc1234

Naming convention worth adopting: keep worktrees as siblings of the repo, named ../repo-<branch>, so they're easy to spot in a file browser and never nested inside the repo itself.

List and inspect worktrees

Human-readable list, with the branch and HEAD of each:

git worktree list

Machine-readable output, useful for scripts:

git worktree list --porcelain

Remove and prune

Remove a worktree once you're done with it:

git worktree remove ../repo-feature-a

Force it if the worktree has uncommitted changes you don't need:

git worktree remove --force ../repo-feature-a

If a worktree's directory was deleted manually instead of through git, clean up the stale metadata:

git worktree prune

Removing a worktree does not delete its branch. Do that separately:

git branch -d feature-a

Move, lock, unlock, repair

Move a worktree to a new path, git updates the metadata for you:

git worktree move ../repo-feature-a ../repo-feature-a-renamed

Lock a worktree so prune and remove leave it alone, for example one on removable media:

git worktree lock ../repo-feature-a

git worktree unlock ../repo-feature-a

If worktree paths moved outside of git's knowledge and metadata is now stale, repair it:

git worktree repair

Common errors and fixes

fatal: '<branch>' is already checked out at '<path>'

That branch is in use in another worktree. Either cd into that worktree, check out a different branch, or remove the other worktree first with git worktree remove.

fatal: '<path>' is a missing but locked worktree

The directory is gone but the worktree was locked, so prune refuses to touch it. Unlock it with git worktree unlock <path>, then git worktree prune or git worktree remove --force <path>.

cannot delete branch '<x>' used by worktree at '<path>'

Git won't delete a branch that's checked out somewhere. Remove that worktree first with git worktree remove <path>, then git branch -d <x>.

Untracked or ignored files missing in the new worktree

A new worktree is a fresh checkout: files git doesn't track, like .env, are not copied over. Copy them manually, or use whatever include mechanism your tooling supports.

Worktrees and AI coding agents

Terminal agents lean on worktrees to run isolated sessions without stepping on each other or on your main checkout. One worktree per agent session is the pattern: claude --worktree <name> creates one under .claude/worktrees/<name> on a new branch, Codex's app puts managed worktrees under $CODEX_HOME/worktrees, and Cursor spins up an isolated checkout per parallel agent. See the full guides for each: Claude Code worktrees, Codex worktrees, and Cursor worktrees and parallel agents.

See them all at once

teebe is a native macOS git worktree GUI that lists every worktree of every repo you add, in one window. Add or remove worktrees straight from its WORKTREES header, and it auto-detects ones created or removed from the terminal, so it never drifts out of sync with what git worktree add and remove actually did. Files badge live as agents touch them, and Space peeks any diff inline without opening an editor. See every git worktree GUI for Mac compared.

Frequently asked questions

How do I create a worktree from an existing branch?

Run git worktree add <path> <branch>, for example git worktree add ../repo-hotfix hotfix. The branch must not already be checked out in another worktree. For a remote branch, fetch first, then run git worktree add -b <branch> <path> origin/<branch>.

How do I delete a worktree and its branch?

First remove the worktree with git worktree remove <path> (add --force if it has changes you don't need). Then delete the branch separately with git branch -d <branch>, or -D to force it. Removing a worktree never deletes its branch.

Why does git say the branch is already checked out?

Git only allows a branch to be checked out in one worktree at a time. If you see fatal: '<branch>' is already checked out at '<path>', either use that existing worktree, check out a different branch, or remove the other worktree first.

Do worktrees share stashes?

Yes. Linked worktrees share the same .git object store with the main worktree, which includes branches, stashes, and remotes. Only HEAD, the index, and the working files are separate per worktree.

Free · open source · macOS 14+. Back to teebe.io →