holocron/plugins/git/.apm/skills/git-worktrees/references/worktrees.md

topic, source_keys

topic	source_keys
worktrees	git-scm-worktree-docs

Git worktrees

Shared vs. per-worktree state

All worktrees share one object store, one config, and most refs under refs/. Each worktree keeps its own HEAD, index, and per-worktree metadata (ORIG_HEAD, MERGE_HEAD, refs/bisect/, refs/worktree/, refs/rewritten/) under $GIT_DIR/worktrees/<name>/. Exactly one main worktree exists per repo — the one git init or git clone produced — and it cannot be removed or moved. Every other worktree is a linked worktree created by git worktree add.

Identifying a worktree

lock, move, remove and repair accept a full path, a unique basename, or a unique partial path. An ambiguous name errors rather than picking one; git worktree list shows the identifiers that are usable.

add forms

git worktree add <path> <branch>              # <branch> exists locally: check it out — non-destructive
git worktree add -b <branch> <path>           # create a new branch; fails if it exists
git worktree add <path>                       # branch named after $(basename <path>): checked out
                                              # if it exists, else created from HEAD
git worktree add -B <branch> <path>           # create the branch, or reset an existing one to HEAD,
                                              # discarding the commits it carried
git worktree add --track -b <branch> <path> <remote>/<branch>
                                              # new local branch tracking the remote — always works
git worktree add <path> <branch>              # <branch> absent locally and in exactly one remote:
                                              # Git expands this to the --track -b form above
git worktree add -d <path>                    # detached HEAD, no branch

The same git worktree add <path> <branch> spelling appears twice above and does two different things: it checks out a local branch when one exists, and only otherwise falls through to the remote-tracking shortcut. Read the local branch list before relying on either.

Do not write git worktree add <path> <remote>/<branch>. A remote-tracking ref resolves as a commit-ish, so the tracking shortcut never fires and the worktree lands on a detached HEAD with no local branch and no upstream — commits there go unreachable once HEAD moves or the worktree is removed, and git push fails without an explicit refspec. That spelling is correct only as the final argument of the --track -b form.

Full add flag table

Flag	Meaning
-b <branch>	Create and check out a new branch; fails if it exists
-B <branch>	Like -b but resets the branch if it already exists
-d / --detach	Detach HEAD; useful for throwaway experiments
--orphan	Create empty unborn branch — Git 2.42+; earlier versions exit 129 with error: unknown option 'orphan'. Fallback below
--no-checkout	Suppress initial checkout (for sparse-checkout setup)
--guess-remote	Look for a matching remote-tracking branch by path basename
--lock [--reason <str>]	Lock immediately on creation (atomic; avoids race vs. add-then-lock)
-f / --force	Allow when branch is already checked out elsewhere
--relative-paths	Link via relative paths (portable across moves)

Using - as <commit-ish> is shorthand for @{-1} (the branch checked out before the current one), e.g. git worktree add <path> -.

New unborn branch

git worktree add --orphan -b <branch> <path>

Creates an empty branch with no commits. --orphan needs Git 2.42 or later — it was added upstream in 2.42, and on 2.39.5 this fails with error: unknown option 'orphan' and exit 129. Check git --version before reaching for it.

Fallback on older Git, verified on 2.39.5 — detach first, then orphan the linked worktree in place, which leaves the main worktree on its own branch throughout:

git worktree add -d <path>       # linked worktree, detached HEAD
cd <path>
git switch --orphan <branch>     # unborn branch: empty index, empty working tree

git worktree list then shows the new worktree at 0000000 [<branch>] until its first commit. Do not substitute git switch --orphan in the main worktree: it clears that checkout, which is the disruption worktrees exist to avoid.

Sparse-checkout worktree

Suppress the initial checkout to configure sparse-checkout first:

git worktree add --no-checkout ../sparse main
cd ../sparse
git sparse-checkout init --cone
git sparse-checkout set src/
git checkout main

Worktree on removable media

git worktree add --lock --reason "external SSD" <path> <branch>
git worktree unlock <path>  # when reconnected

Remote-branch disambiguation

git worktree add --track -b <branch> <path> <remote>/<branch>   # explicit: no guessing at all
git worktree add <path> <branch>                                # shortcut: needs one clear remote

The bare-name shortcut needs exactly one remote. It fires only when <branch> is not found locally, none of -b/-B/--detach were given, and a tracking branch of that name exists in exactly one remote. When several remotes carry the name, checkout.defaultRemote picks one for disambiguation purposes; with no such setting the shortcut has no single remote to resolve against and does not apply. When the remote is ambiguous or unknown, use the explicit --track -b form.

--guess-remote covers the other spelling — git worktree add <path> with no <commit-ish> at all. It bases the new branch on the remote-tracking branch matching $(basename <path>) when exactly one remote has it, and marks that branch as upstream. Its default comes from the worktree.guessRemote config.

Repair after a manual move

git worktree repair            # the MAIN worktree moved: run it there to reconnect every linked
                               # worktree back to the main worktree
git worktree repair            # a LINKED worktree moved: run it inside that recently-moved worktree
git worktree repair <path>...  # reconnect a specific linked worktree — runnable from any worktree,
                               # naming each moved tree's new path

Which form applies depends on what moved:

What moved	Remedy
The main worktree (or bare repo)	git worktree repair in the main worktree
One linked worktree	git worktree repair inside that worktree
Several linked worktrees	git worktree repair <path>... from any worktree, listing each new path
Both main and linked worktrees	git worktree repair <path>... in the main worktree, naming each linked worktree's new path — this restores the connections in both directions

Only the no-argument form is tied to the current directory. The <path>... form is not — it reestablishes the connection to every path you name, run from any worktree.

Configuration

Key	Effect
worktree.guessRemote	Default for --guess-remote on git worktree add
worktree.useRelativePaths	Default for --relative-paths on git worktree add (link via relative paths — portable across moves)
gc.worktreePruneExpire	How long before stale worktree metadata is pruned by git gc
extensions.worktreeConfig	Enable per-worktree config scope (config.worktree file) — see Gotchas in SKILL.md
checkout.defaultRemote	Disambiguates which remote to use when a branch name matches multiple remotes during worktree add

Workflow patterns

Emergency fix without disrupting current work — nothing is stashed, and the main worktree is untouched throughout:

git worktree add -b emergency-fix ../temp main
cd ../temp
# fix, then commit
git commit -a -m "fix: critical production bug"
cd -
git worktree remove ../temp

Review a PR branch alongside your own work — both branches stay checked out, so there is no context switch:

git worktree add ../review-pr-123 origin/feature-xyz          # detached HEAD — read-only review
git worktree add --track -b feature-xyz ../review-pr-123 origin/feature-xyz   # if you will commit
# open ../review-pr-123 in a second editor window or terminal

Pick the second form the moment you intend to push anything back: the first leaves no branch to push and no upstream to push to.