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.

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
# 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 pathsA linked worktree does not contain a .git directory. It contains a file:
gitdir: /home/ryu/project/.git/worktrees/project-hotfixEverything 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
| Item | Shared between worktrees | Separate per worktree |
|---|---|---|
| Object database, packs | Yes | — |
| Branches, tags, remotes | Yes (refs) | — |
HEAD and its reflog | — | Yes |
| Index | — | Yes |
| Working files | — | Yes |
| Stash | Yes | — |
| Hooks | Yes (core.hooksPath is shared) | --worktree config only |
| Sparse-checkout patterns | — | Yes (per worktree) |
node_modules, build caches | — | Yes, duplicated on disk |
| Need | Worktree | Second clone | Stash + switch |
|---|---|---|---|
| Two branches open at once | Yes | Yes | No |
| Shared refs and stash | Yes | No | Yes |
| Disk cost | Working files only | Full object store | None |
| Safe for a long-running build | Yes | Yes | No |
| One branch in two places | Refused | Allowed, then conflicts on push | N/A |
Practical Edge Cases and Deep Dives
1. "already checked out at": the one-branch rule
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:
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
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 pruneDeleting 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
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/uiSubmodule 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
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
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/mainThis 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
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 rootScripts 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
| Symptom | Cause | Fix |
|---|---|---|
'main' is already checked out at ... | Branch owned by another worktree | -b a new branch, or --detach |
Worktree missing from list but branch still blocked | Directory deleted by hand | git worktree prune |
fatal: not a git repository: .git/worktrees/... | Repository moved or renamed | git worktree repair |
| Submodule directories empty | Worktree checkout does not init submodules | git submodule update --init --recursive |
| Sparse patterns unexpectedly applied | Sparse-checkout is per worktree | Set patterns per worktree |
user.email changed everywhere | git config --worktree used without extensions.worktreeConfig | Enable it, then re-set per worktree |
worktree remove refuses | Dirty tree or locked worktree | Commit, then --force if intended |
| Disk full after three worktrees | node_modules and caches duplicated | Share a package store, or --no-checkout + symlinked deps |
| Hooks behave differently in the new worktree | core.hooksPath is shared, relative paths are not | Use an absolute hooks path |
Try matching browser tools
All toolsSmall utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Git guides
All Git guidesGit config: Aliases, rerere, and Credential Helpers
Five config scopes decide one value at a time. Aliases are user-level shorthand, rerere records conflict resolutions, and credential helpers choose where your secret lives.
Git Hooks: pre-commit, commit-msg, and Husky Automation
Hooks live in .git/hooks, which a clone never receives, so core.hooksPath and Husky are how they travel. Exit codes abort the operation, and every hook is bypassable.
Git bisect: Binary Search, Automated Scripts, and Bug Hunting
Mark one bad and one good commit and Git halves the range each step. bisect run automates it through exit codes, and monotonicity is the assumption that must hold.
Git ignore: Patterns, Negation, and Untracking Cached Files
Patterns are relative and last match wins, but a negation cannot revive a file inside an excluded directory. Ignore rules never touch tracked files: rm --cached first.
More in Git
All Git guidesThe guides filed next to this one in Git, in library order.