Git Worktree Cheat Sheet: Commands, Examples, and Pitfalls

git worktree lets one repository have several working directories at once. Each worktree has its own checked-out branch, HEAD, and index, while commits, branches, and configuration stay shared. Day to day you need four commands: git worktree add to create one, git worktree list to see them, git worktree remove to delete a clean one, and git worktree prune to tidy up after folders you deleted by hand.

Every command and flag below matches the official git-worktree reference, whose manual was last updated for Git 2.56, as reviewed on October 5, 2026. git worktree has shipped with Git since version 2.5 in July 2015. Two newer flags need a recent Git: --orphan arrived in 2.42 and --relative-paths in 2.48. Check yours with git --version.

Git worktree command cheat sheet#

Task	Command	Notes
New worktree and branch, named after the folder	git worktree add ../hotfix	Creates branch hotfix from HEAD; if hotfix already exists and isn't checked out elsewhere, Git checks it out instead
New branch from a chosen base	git worktree add -b feature/search ../app-search origin/main	-B resets an existing branch to the base instead of refusing
Existing local branch	git worktree add ../app-review feature/search	Refused if the branch is checked out in another worktree
Branch that exists only on the remote	git fetch origin then git worktree add ../app-fix fix/typo	If exactly one remote has fix/typo, Git creates a local branch tracking it
The same, spelled out	git worktree add --track -b fix/typo ../app-fix origin/fix/typo	Use when several remotes have the branch
Throwaway checkout, no branch	git worktree add -d ../app-scratch	Detached HEAD at your current commit
Check out a tag or commit	git worktree add --detach ../app-v2 v2.0.0	Good for reproducing an old release
Empty branch with no history	git worktree add --orphan -b gh-pages ../site	Git 2.42 or later
Create without checking files out	git worktree add --no-checkout ../app-sparse release/2.0	Configure sparse checkout before populating it
Create and lock in one step	git worktree add --lock --reason "external drive" /Volumes/usb/app-docs docs/refresh	Avoids a race between add and lock
List worktrees	git worktree list	Main worktree first; shows commit, branch, locked, prunable
List with reasons	git worktree list -v	Prints lock and prune reasons
List for scripts	git worktree list --porcelain -z	Stable format across Git versions
Remove a clean worktree	git worktree remove ../app-search	Refuses if there are changes or untracked files
Remove one with changes	git worktree remove --force ../app-search	Locked worktrees need --force twice
Preview stale metadata	git worktree prune --dry-run --verbose	Reports what would be removed
Remove stale metadata	git worktree prune	Only for worktrees whose folders are already gone
Move a worktree	git worktree move ../app-search ../archive/app-search	Not for the main worktree or ones with submodules
Lock and unlock	git worktree lock --reason "on NAS" ../app-nas / git worktree unlock ../app-nas	Locked worktrees aren't pruned, moved, or deleted
Reconnect after a manual move	git worktree repair	Run it in the moved worktree, or pass new paths from the main one
Per-worktree settings	git config extensions.worktreeConfig true then git config --worktree <key> <value>	Repository config is shared by default
Delete the branch afterwards	git branch -d feature/search	Removing a worktree leaves its branch in place

Every example that names an existing branch assumes it isn't checked out anywhere else. That includes main: if your main folder has it checked out, git worktree add ../app-main main is refused, so branch from origin/main with -b instead.

Two shortcuts help. Any command that takes a worktree accepts a unique final path component, so git worktree remove app-search works when no other worktree ends in app-search. And because origin/main is a remote-tracking branch, -b ... origin/main makes it the new branch's upstream; push the first time with git push -u origin <branch>, or add --no-track if you don't want that.

What worktrees share, and what they don't#

Shared by every worktree	Separate in each worktree
Commits and other objects	Working files on disk
Branches, tags, and remote-tracking branches	HEAD (what is checked out)
The stash, because refs/stash is a shared ref	The index (what is staged)
Remotes and repository config, unless you enable per-worktree config	Untracked and ignored files: .env, node_modules, build output
	Bisect state and other per-worktree refs

Git's rule is simple: refs under refs/ are shared, except refs/bisect, refs/worktree, and refs/rewritten, while pseudo refs such as HEAD belong to one worktree. Each linked worktree keeps its private metadata in .git/worktrees/<name> in the main repository, and its own .git is a small file pointing there.

Common workflows#

Ship a hotfix without touching your feature branch#

Your feature checkout keeps its half-finished state, running dev server, and editor tabs. Nothing gets stashed.

Review a pull request in its own folder#

On GitHub, every pull request is fetchable as pull/<number>/head:

When you're done, remove the worktree and the temporary branch:

Give each AI coding agent its own checkout#

Two agents in one folder overwrite each other's files and build output. One worktree per agent fixes that:

The agents still share your machine, so ports, databases, and global caches can collide. Setting up .env, ports, and databases per worktree covers that layer, and worktrees vs containers explains when a worktree isn't enough isolation.

Keep every branch as a sibling folder#

Some people clone bare and treat every branch, including main, as a worktree:

The git config line matters. A bare clone creates no remote-tracking branches and no fetch configuration for them, so without it git fetch won't maintain origin/*. And because a bare repository has no working tree, main isn't checked out anywhere yet, so it can have a worktree of its own.

Git worktree vs branch vs stash vs clone#

	Switch branches	Stash	Worktree	Second clone
What it is	Change what one folder has checked out	Shelve uncommitted changes	Another folder linked to the same repository	Another repository
Two tasks open at once	No	No	Yes	Yes
Extra disk	None	None	One more checkout, plus its dependencies and build output	One more checkout and .git (a clone of a local path hardlinks objects when possible)
Shares commits and branches	n/a	n/a	Yes, instantly	Only through fetch and push
Shares config and remotes	n/a	n/a	Yes, by default	No
Main risk	Uncommitted changes come along or block the switch	Forgotten stashes; untracked files need git stash -u	Ignored files are missing; one branch per worktree	Clones drift apart
Best for	Sequential work	Short interruptions	Parallel work, reviews, hotfixes, agents	Fully separate settings or experiments

A branch and a worktree aren't alternatives: the branch is what you work on, and the worktree is where you work on it. The real choice is between switching one folder back and forth (branches and stash) and keeping several folders open (worktrees and clones). Worktrees win the second contest for most people because a commit in one is instantly visible in the others.

Pitfalls and how to fix them#

The same branch can't be checked out twice#

git worktree add refuses a branch that another worktree already has checked out. Use -d to look at the same commit in detached mode, create a new branch with -b, or switch the other worktree to a different branch. --force overrides the check, but then two checkouts move one branch.

.env, node_modules, and build output aren't copied#

A new worktree contains tracked files only. Everything ignored, including environment files, dependencies, and generated code, has to be recreated:

Don't symlink one node_modules into several worktrees. Branches can have different dependencies, and an install in one would change the other. If disk use is the worry, pnpm hard-links packages from a content-addressable store, so a second install of the same versions costs little extra space. Tools can automate the copying: Claude Code and the Codex app read a .worktreeinclude file, and Agentastic runs a setup script for every new worktree.

Deleting the folder by hand leaves metadata behind#

rm -rf ../app-search removes the files but not the entry in .git/worktrees. git worktree list then marks it prunable. Run git worktree prune, or let Git expire it automatically through gc.worktreePruneExpire. Next time, use git worktree remove.

remove refuses, or leaves the branch#

git worktree remove only removes clean worktrees: commit or stash first, or pass --force. A locked worktree needs --force twice, and the main worktree can't be removed at all. The branch survives removal; delete it with git branch -d, or -D if it was never merged.

Submodules are only partly supported#

Git's own documentation calls multiple checkouts experimental, says submodule support is incomplete, and recommends against multiple checkouts of a superproject. In practice, removing a worktree with submodules needs --force, and git worktree move can't move it. If a new worktree's submodule folders are empty, run git submodule update --init --recursive inside it.

Moved folders lose their link#

Move worktrees with git worktree move. If you already moved one, or moved the main repository, run git worktree repair. For setups that travel between machines or containers, worktree.useRelativePaths (or --relative-paths on a single command) links worktrees with relative paths. Turning the setting on also enables a repository extension that older Git versions can't read.

Worktrees inside the repository show up as untracked#

Put worktrees in a sibling folder, or add the folder you use, such as .claude/worktrees/, to .gitignore.

How Claude Code, Codex, and Agentastic use worktrees#

Claude Code. claude --worktree <name> (or -w) creates a worktree under .claude/worktrees/<name>/ on a new branch named worktree-<name>. A .worktreeinclude file in .gitignore syntax copies matching ignored files such as .env. The worktree.baseRef setting chooses between the remote default branch ("fresh", the default) and your current HEAD ("head"), and claude --worktree "#1234" branches from a pull request. On exit, Claude removes clean worktrees from unnamed sessions and asks about the rest. While an agent runs, Claude Code holds a git worktree lock on its worktree, so git worktree remove refuses until it's unlocked. See Anthropic's worktree guide.

Codex app. Codex-managed worktrees live in $CODEX_HOME/worktrees, start in detached HEAD, and copy ignored files listed in .worktreeinclude. By default the app keeps your 15 most recent managed worktrees, and Handoff moves a chat between your local checkout and its worktree. See OpenAI's worktree docs and how to run Codex agents in parallel.

Agentastic. Agentastic creates a branch and worktree for each task and stores them next to the repository in repo-worktrees/ by default, inside the repository in .worktree/, or under ~/worktrees/. Every new worktree runs .agentastic/setup.sh, which receives variables such as AGENTASTIC_MAIN_REPO_PATH, so copying .env files and installing dependencies become part of creating the workspace. Start from origin forks from the latest origin/<base>, the base picker can check out an open pull request, and Ctrl+Tab switches between worktrees. When files aren't enough isolation, the same workspace can run in a container. Agentastic is macOS only. Details are in the Git Worktrees docs.

For a broader comparison of worktree tools, from raw Git to Conductor and Superset, see Git worktree tools for AI coding agents. To try the Agentastic workflow, download it for macOS.

Sources and further reading#

• git-worktree reference — git-scm.com
• git-clone reference (--bare, --local) — git-scm.com
• Git 2.5 release notes — git/git on GitHub
• Checking out pull requests locally — GitHub Docs
• Run parallel sessions with worktrees — Claude Code docs
• Worktrees — Codex docs
• Motivation: the content-addressable store — pnpm
• Git Worktrees — Agentastic docs
• Setup & Teardown Scripts — Agentastic docs
• Run multiple Claude Code agents in parallel
• Parallel Claude Code worktree problems

Frequently asked questions#

What is git worktree used for?#

git worktree lets one repository have several working directories at once, each with its own checked-out branch. People use it to make a hotfix without stashing a half-finished feature, to review a pull request in a separate folder, to run two builds side by side, and to give each AI coding agent its own checkout.

How do I add a git worktree for an existing branch?#

Run git worktree add with a new folder and the branch name, for example git worktree add ../app-review feature/search. If the branch exists only on a remote, fetch first; when exactly one remote has a matching branch, Git creates a local branch that tracks it. Git refuses if the branch is already checked out in another worktree.

What is the difference between git worktree remove and git worktree prune?#

git worktree remove deletes a worktree's folder and its metadata, and only works on a clean worktree unless you add --force. git worktree prune deletes leftover metadata for worktrees whose folders are already gone, for example after you deleted one with rm -rf.

What is the difference between a git worktree and a branch?#

A branch is a named pointer to a commit. A worktree is a directory where a branch, or a detached commit, is checked out, with its own HEAD and index. You use them together: each worktree usually has its own branch.

Should I use git worktree or clone the repository twice?#

Use a worktree when you want a second checkout of the same project: it shares commits, branches, remotes, and configuration, so a commit made in one worktree is visible in the others immediately. Use a second clone when you need a fully independent repository with its own configuration and remotes.

Does git worktree copy .env files and node_modules?#

No. A new worktree contains only tracked files, so ignored files such as .env, node_modules, and build output are missing. Copy the environment files you need and install dependencies inside each worktree, or automate it with .worktreeinclude in Claude Code and Codex or a setup script in Agentastic.

Can two git worktrees use the same branch?#

Not by default. Git refuses to check out a branch that is already checked out in another worktree. Use a detached HEAD to look at the same commit, or create a new branch; --force overrides the check, but then two checkouts move one branch.