Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git worktree: Multiple Checked-Out Branches in One Repository

A linked worktree has its own HEAD, index, and files while sharing objects and refs. One branch per worktree, prune for deleted directories, and submodules that stay empty.

~4 min readGit
#Git#Worktree#Branching#CLI
3D illustration of one repository cube with three working folder slabs branching off

Quick Summary

A linked worktree is a second checked-out directory attached to the same repository. Each one has its own HEAD, index, and working files, and all of them share the object database, refs, tags, stash, hooks, and remotes. Two branches can therefore be open at once without stashing, switching, or a second clone.

The common use is a hotfix while a long build or a half-finished refactor sits in your main checkout. Others are comparing two versions side by side, running tests against an old release, or deploying from a bare repository whose worktrees are the web roots.

The constraint that surprises people is one branch per worktree: git switch to a branch already checked out elsewhere is refused, because two indexes writing to one branch would race. And because every worktree duplicates the working files, the disk cost is real on a monorepo with a large node_modules.

Basic Syntax and Core Signatures

bash
# Create git worktree add ../project-hotfix hotfix/2.1.1 # existing branch git worktree add -b fix/login ../project-login origin/main # new branch from a ref git worktree add --detach ../project-v2 v2.0.0 # detached at a tag git worktree add --no-checkout ../project-bare main # empty tree, index only # Inspect git worktree list git worktree list --porcelain # Remove git worktree remove ../project-hotfix # refuses if dirty git worktree remove --force ../project-hotfix git worktree prune # forget deleted directories git worktree lock ../project-usb # protect from prune git worktree unlock ../project-usb git worktree move ../project-hotfix ../hotfix # Git 2.17+ git worktree repair # Git 2.30+: fix moved/linked paths

A linked worktree does not contain a .git directory. It contains a file:

text
gitdir: /home/ryu/project/.git/worktrees/project-hotfix

Everything under that gitdir, plus the shared repository directory it points back to, is what makes the second directory a worktree rather than a copy.

Key Comparison Table

ItemShared between worktreesSeparate per worktree
Object database, packsYes—
Branches, tags, remotesYes (refs)—
HEAD and its reflog—Yes
Index—Yes
Working files—Yes
StashYes—
HooksYes (core.hooksPath is shared)--worktree config only
Sparse-checkout patterns—Yes (per worktree)
node_modules, build caches—Yes, duplicated on disk
NeedWorktreeSecond cloneStash + switch
Two branches open at onceYesYesNo
Shared refs and stashYesNoYes
Disk costWorking files onlyFull object storeNone
Safe for a long-running buildYesYesNo
One branch in two placesRefusedAllowed, then conflicts on pushN/A

Practical Edge Cases and Deep Dives

1. "already checked out at": the one-branch rule

bash
git worktree add ../hotfix main # fatal: 'main' is already checked out at '/home/ryu/project'

Git refuses because the branch ref would be advanced from two indexes. Three legitimate resolutions:

bash
git worktree add -b hotfix/main ../hotfix main # new branch from main, detached from it git worktree add --detach ../hotfix main # read-only comparison, no branch git -C ../hotfix switch --detach # move an existing worktree off the branch

--force exists (git worktree add --force) and produces exactly the split state the check prevents; it is meant for repairing a worktree whose ref was already moved by hand, not for routine use.

2. Pruning and the directory you deleted with rm -rf

bash
rm -rf ../project-hotfix git worktree list # /home/ryu/project 3f2a1b9 [main] # /home/ryu/project-hotfix 9c1e2f4 [hotfix/2.1.1] prunable: gitdir file points to non-existent location git worktree prune --dry-run git worktree prune

Deleting the directory by hand leaves the metadata under .git/worktrees/ behind, and the branch stays marked as checked out there, so you cannot check it out in the main tree. git worktree prune clears stale entries; git worktree lock marks a worktree on a removable or network volume so prune skips it while the volume is offline.

3. Submodules and sparse-checkout do not follow

bash
git worktree add ../review pr-42 cd ../review git submodule update --init --recursive # required: submodules are NOT populated git sparse-checkout init --cone # per-worktree, independent patterns git sparse-checkout set app packages/ui

Submodule gitlinks are recorded in the tree, but a new worktree checks out the tree and leaves the submodule directories empty; every tool that assumes submodules exist (a build script, an editor indexer) fails until submodule update --init runs. Sparse-checkout, by contrast, is per-worktree state, so a sparse main checkout does not limit the new worktree, and git sparse-checkout inside one does not affect the other.

4. Per-worktree configuration

bash
git config extensions.worktreeConfig true # required once, then: git config --worktree core.sparseCheckout true git config --worktree user.email "release-bot@example.com"

Ordinary git config writes to the shared config, so setting user.email for a release worktree silently changes it for every worktree. extensions.worktreeConfig enables git config --worktree, which writes into .git/worktrees/<name>/config.worktree. Hooks cannot be varied this way — core.hooksPath is repository-wide — so a worktree-specific hook policy needs a wrapper script that reads git rev-parse --git-dir.

5. Deployment from a bare repository

bash
git clone --bare git@github.com:org/site.git /srv/site.git cd /srv/site.git git worktree add --detach /srv/www/current main git -C /srv/www/current fetch origin main git -C /srv/www/current reset --hard origin/main

This keeps a full history in one place and a clean, git-tracked tree in the web root, without a .git directory exposed to the document root. git worktree add --detach is right here: the deployment does not own a branch, and reset --hard origin/main moves it forward on each release. The classic failure is a web server that writes into that tree; git reset --hard then deletes uploads, so keep generated files outside it.

6. Worktrees and tooling that assumes one checkout

bash
git rev-parse --git-common-dir # shared repo dir git rev-parse --git-dir # this worktree's gitdir git rev-parse --show-toplevel # this worktree's root

Scripts that hardcode .git as a directory break in a worktree, because it is a file there; read the path from git rev-parse --git-dir instead. Editors handle linked worktrees well when the project root is the worktree, but a language server indexing both checkouts will report duplicate symbols and stale caches twice. If a build tool needs an exclusive lock (a test database, a fixed port), running the same suite in two worktrees at once fails; give each worktree its own .env and port.

One placement rule saves a lot of confusion: create worktrees beside the repository, not inside it. A worktree nested under the main checkout appears as untracked content to the outer repository, so git status shows it, git clean -fdx can delete it, and a build tool that walks the tree indexes the same source twice. ../project-hotfix keeps the two trees siblings and the outer status clean.

Common Git Operation Mistakes

SymptomCauseFix
'main' is already checked out at ...Branch owned by another worktree-b a new branch, or --detach
Worktree missing from list but branch still blockedDirectory deleted by handgit worktree prune
fatal: not a git repository: .git/worktrees/...Repository moved or renamedgit worktree repair
Submodule directories emptyWorktree checkout does not init submodulesgit submodule update --init --recursive
Sparse patterns unexpectedly appliedSparse-checkout is per worktreeSet patterns per worktree
user.email changed everywheregit config --worktree used without extensions.worktreeConfigEnable it, then re-set per worktree
worktree remove refusesDirty tree or locked worktreeCommit, then --force if intended
Disk full after three worktreesnode_modules and caches duplicatedShare a package store, or --no-checkout + symlinked deps
Hooks behave differently in the new worktreecore.hooksPath is shared, relative paths are notUse an absolute hooks path

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.