Creating
Introduction
A linked worktree is a second checkout of the same repository. It shares objects, refs, and config, but keeps its own HEAD, index, and files.
They suit parallel branches, review, hotfixes, and one checkout per agent.
- git-worktree manual (git-scm.com)
- Pro Git: Worktrees (progit3.com)
- gitrepository-layout (git-scm.com)
Add a worktree
git worktree add ../hotfix hotfix
git worktree add ../next
git worktree add ../fix -b fix main
The first form checks out an existing branch. Without a branch, add checks
out or creates the branch named after the path. -b creates a branch from a
start point, HEAD by default. The path must be empty or missing.
See: git worktree add
Branch options
git worktree add --track -b topic ../topic origin/main
git worktree add -B reset ../reset main
git worktree add --orphan -b empty ../empty
git worktree add ../prev -
--track marks a start point as upstream; it is implied for a remote-tracking
branch. -B resets an existing branch. --orphan starts an unborn branch with
an empty index. A bare - means @{-1}, the previous branch.
See: git worktree options
Detached checkouts
git worktree add --detach ../review origin/main
git worktree add --no-checkout -b sparse ../sparse main
--detach leaves HEAD off any branch, so a review worktree cannot claim a
branch. --no-checkout skips the initial checkout for sparse or custom setups.
See: git worktree options
Inspecting
List worktrees
git worktree list
git worktree list -v
git worktree list --porcelain
Output
| Annotation | Meaning |
|---|---|
bare | a bare repository entry |
detached | HEAD is not on a branch |
locked | protected from prune, move, and remove |
prunable | the worktree directory is missing |
The default output shows the path, current commit, and branch or detached HEAD. -v adds lock reasons; --porcelain emits stable key value records
for scripts. bare and detached appear in the default output; locked and
prunable are appended.
See: List output format
Where worktrees live
cat ../hotfix/.git
# gitdir: /repo/.git/worktrees/hotfix
Shared state
| Shared | Per worktree |
|---|---|
| objects, refs, config, hooks | HEAD, index, sparse patterns |
Each linked worktree has a private directory under .git/worktrees/<id>
holding its HEAD and index; its .git file points there. Objects, refs,
config, and hooks stay shared.
See: gitrepository-layout
Managing
Remove a worktree
git worktree remove ../hotfix
git worktree remove --force ../dirty
remove deletes the directory and its admin entry, but leaves the branch and
its commits. It refuses modified or untracked files; --force discards them.
A locked worktree needs --force twice. The main worktree cannot be removed.
See: git worktree remove
Prune stale entries
git worktree prune -n -v
git worktree prune
prune removes admin entries whose worktree directory is gone, which happens
after a manual rm -rf. -n reports without removing; -v names each entry.
Automatic pruning runs from git gc after gc.worktreePruneExpire, three
months by default.
Lock a worktree
git worktree lock --reason "usb drive" ../hotfix
git worktree unlock ../hotfix
Locking prevents prune, move, and remove from touching the entry. Use it
for worktrees on removable or network paths. add --lock locks at creation
without a race window.
See: git worktree lock
Move and repair
Move
git worktree move ../hotfix ../hotfix-2
After a manual move
git worktree repair ../hotfix-2
move updates the admin files. If you move a directory by hand, the entry
becomes prunable; run repair from the moved worktree, or in the main
worktree with its new path. Main and submodule worktrees cannot be moved.
See: git worktree repair
Rules
One branch, one worktree
git worktree add ../other main
# fatal: 'main' is already used by worktree at '/repo'
A branch can be checked out in only one worktree; git checkout enforces the
same rule. --force overrides it, but two checkouts invite lost commits. Use a
detached worktree when the same commit is enough.
See: git worktree add
Config and hooks
git config extensions.worktreeConfig true
cd ../hotfix
git config --worktree core.sparseCheckout true
Config is shared by default: remotes, aliases, and hooks all come from the main
.git. With extensions.worktreeConfig, git config --worktree writes the
linked worktree's config.worktree, which is read after the shared config.
See: Configuration file
Sparse checkout
git worktree add --no-checkout -b sparse ../sparse main
cd ../sparse
git sparse-checkout set --cone src docs
git read-tree -mu HEAD
Patterns live in .git/worktrees/<id>/info/sparse-checkout, and set turns
on extensions.worktreeConfig so core.sparseCheckout stays per worktree.
read-tree fills the empty index.
See: git-sparse-checkout
Submodules
| Operation | Submodule effect |
|---|---|
remove | needs --force |
move | refuses |
| multiple checkouts | experimental, incomplete |
Git still calls multiple checkouts experimental and warns that submodule
support is incomplete. Avoid multiple checkouts of a superproject, and
expect --force when removing one that carries submodules.
See: git worktree bugs
Workflows
Parallel branches
git worktree add ../feat -b feat main
git worktree add ../fix -b fix main
Each checkout has its own index, working files, and build directory, so a dirty feature tree never blocks a fix. Switch context by changing directory, not by stashing.
Review a pull request
git fetch origin pull/123/head
git worktree add --detach ../review FETCH_HEAD
The fetch ref works on GitHub and other forges that expose pull/<n>/head. A
detached worktree keeps the review off your branch list; remove it when the
review lands.
Hotfix while mid-feature
git worktree add -b hotfix ../hotfix main
cd ../hotfix && npm test
The hotfix builds and tests in its own directory while the feature checkout
stays dirty. Commit on hotfix, then remove the worktree; the branch and
commit remain.
Bare repository hub
git clone --bare git@github.com:me/repo.git repo.git
git -C repo.git worktree add ../main main
A bare repository has no checkout of its own, so each checkout lives in a sibling directory while sharing one object store. This layout suits dotfiles and build hosts.
See: git clone --bare
One worktree per agent
git worktree add -b task-42 ../wt-42 origin/main
git worktree remove ../wt-42
Each agent gets an isolated index and working directory while objects and refs stay shared, so creating one is cheap. Name worktrees after the task or agent, and remove them when the run finishes. Avoid two agents on one branch.
See: git-worktree
0 Comments for this cheatsheet. Write yours!