Git Worktree
debt(d7/e3/b2/t5)
Closest to 'only careful code review or runtime testing' (d7). detection_hints.automated is 'no' and the only tool is git itself; the misuse pattern (repeated stash/pop or re-cloning) is a workflow habit invisible to any linter, surfacing only when someone notices wasted disk or lost context. Stale worktree admin entries are silent until git worktree list or a blocked checkout reveals them.
Closest to 'simple parameterised fix' (e3). quick_fix is a small command swap: replace stash-and-switch or re-clone with `git worktree add ../hotfix main` and `git worktree remove` when done. Cleaning up stale entries is `git worktree prune`. It's a workflow correction, not a code refactor, but slightly more than a one-line patch.
Closest to 'localised tax' (b3), edging toward b1. applies_to is cli only and worktrees are a per-developer workflow choice that doesn't shape the system's architecture or impose weight on every maintainer. The main risk is local clutter (nested trees, abandoned worktrees) which stays confined to one developer's environment.
Closest to 'notable trap' (t5). The misconception (you must re-clone for a second branch) plus common_mistakes — expecting full isolation when hooks/config/submodules are shared, same branch refused in two worktrees, rm instead of git worktree remove leaving stale entries — are documented gotchas most users eventually learn, matching the t5 anchor.
Also Known As
TL;DR
Explanation
Git worktree lets a single repository have multiple working trees checked out simultaneously, each on its own branch, sharing the same .git object store. Instead of stashing changes to switch branches, or cloning the repo twice to work on a feature and a hotfix in parallel, you run `git worktree add ../hotfix main` and get a separate directory tied to the same repository. Each worktree has its own index, HEAD, and checked-out files, but commits, refs, and objects are shared - so a fetch in one worktree is visible in all of them. Common uses: building a release branch while continuing feature work, running long test suites on one branch while editing another, reviewing a PR branch without disturbing your current state, or letting an editor keep an isolated environment per task. Constraints: the same branch cannot be checked out in two worktrees at once (git refuses to prevent conflicting index states), and a detached HEAD is allowed if you need the same commit in two places. Worktrees are managed with `git worktree list`, `git worktree remove`, and `git worktree prune` to clean up stale administrative entries left when a directory is deleted manually. Linked worktrees store their metadata under .git/worktrees/<name>, and the worktree directory contains a .git file (not folder) pointing back to the main repository. Worktree is faster and lighter than a second clone because objects are not duplicated, but it shares the same submodule and hook configuration, so each worktree is not fully independent. It is a built-in feature since Git 2.5, requires no extra tooling, and pairs well with rebase, bisect, and CI checkout flows where you want a clean tree separate from your daily work.
Common Misconception
Why It Matters
Common Mistakes
- Trying to check out the same branch in two worktrees - git refuses to avoid conflicting index state.
- Deleting a worktree directory with rm instead of git worktree remove, leaving stale admin entries that need git worktree prune.
- Forgetting that worktrees share hooks, config, and submodule state, expecting full isolation like a separate clone.
- Adding worktrees inside the main working tree, causing confusing nested git paths.
- Not running git worktree list, so abandoned worktrees accumulate and block branch checkouts.
Avoid When
- You need fully isolated config, hooks, or submodule state - a separate clone is cleaner.
- Your build writes absolute paths or caches that assume a single working directory.
- Disk is tight and you only ever work one branch at a time - the extra checked-out tree is unnecessary.
- Tooling cannot handle the .git file pointer used by linked worktrees.
When To Use
- Handling an urgent hotfix while keeping a long-lived feature branch checked out.
- Running a slow test suite or build on one branch while editing another.
- Reviewing a PR branch in a clean directory without stashing current work.
- Bisecting or rebasing in an isolated tree so your daily working directory stays stable.
Code Examples
# Need to fix a hotfix while mid-feature - stash juggling:
git stash push -m 'WIP feature'
git checkout main
# ... make hotfix, commit, push ...
git checkout feature/big-refactor
git stash pop # hope nothing conflicts
# Or worse - clone the whole repo again (duplicates all history):
git clone git@github.com:org/repo.git ../repo-hotfix # gigabytes copied# Create a linked worktree on main, sharing the same object store:
git worktree add ../repo-hotfix main
cd ../repo-hotfix
# ... make hotfix, commit, push - feature work untouched ...
# Inspect and clean up (from any worktree; tree must be clean):
cd -
git worktree list
git worktree remove ../repo-hotfix
git worktree prune # clear any stale admin entries
# Detached worktree for reviewing a PR commit without a branch:
git worktree add --detach ../pr-review origin/feature-x