Git Worktrees — Glossary
Quick-reference definitions for the concepts in the
Git Worktrees for Parallel Agentic Coding
course. Designed for printing.
Core Concepts
- Worktree
-
A working tree (directory of checked-out files) attached to a git
repository. Every git repository starts with one — the
main worktree. Additional worktrees can be created with
git worktree add.
- Main Worktree
-
The original worktree created when you ran
git clone or
git init. Its .git is a
directory containing the full git database.
Distinguished from linked worktrees by having the real
.git/ directory rather than a pointer file.
Linked Worktree, Pointer File
- Linked Worktree
-
Any worktree created with
git worktree add beyond the
main worktree. Its .git is a file (not a
directory) that points to metadata in the main worktree's
.git/worktrees/<name>/.
- Pointer File (
.git file)
-
In a linked worktree,
.git is not a directory — it's a
single file containing the line
gitdir: /path/to/main/.git/worktrees/name/. This is how
git knows which worktree-specific metadata (HEAD, index, reflog) to
use. Run cat .git to see it.
- Worktree Metadata (
.git/worktrees/)
-
A directory in the main worktree's
.git/ that contains
per-worktree state: HEAD, index,
ORIG_HEAD, logs/, commondir,
and gitdir. Each linked worktree has one subdirectory
here. Orphaned entries (from rm -rf) can be cleaned with
git worktree prune.
Commands
git worktree add <path> [<branch>]-
Create a new worktree at
<path>. If
<branch> is specified, check it out. With
-b <name>, create a new branch simultaneously. With
--detach, check out a specific commit in detached HEAD.
The path must not already exist and must be outside the current
worktree.
git worktree list-
Show all worktrees: path, commit hash, and branch name (or "detached
HEAD"). Add
--porcelain for machine-parseable output. Add
-v / --verbose for additional detail.
git worktree remove <path>-
Safely remove a worktree. Refuses if the worktree has uncommitted
changes (override with
--force). Also cleans up the
metadata in .git/worktrees/. Always prefer this over
rm -rf.
git worktree prune-
Remove metadata for worktrees whose directories no longer exist (e.g.,
if someone used
rm -rf). Safe to run anytime — only
removes entries where the worktree directory is confirmed gone. Add
--expire <time> to only prune entries older than a
threshold.
git worktree lock <path>-
Prevent a worktree from being pruned (e.g., if it's on removable
media). Unlock with
git worktree unlock <path>.
git worktree move <path> <new-path>-
Move a worktree to a new location. Updates the pointer file and
metadata. Safer than
mv because it also updates all
internal references.
git worktree repair <path>-
Repair worktree metadata if the main worktree was moved or the paths
are broken. Useful after moving a repo to a new location.
Concepts for Reasoning
- Shared vs. Isolated State
-
The fundamental invariant of worktrees. Shared across
all worktrees: object database (
.git/objects/), refs
(.git/refs/), config, hooks.
Isolated per worktree: working tree files, index
(staging area), HEAD, reflog. A commit made in any worktree is
immediately visible in all others; a staged change is visible only in
the worktree where it was staged.
- One-Branch-Per-Worktree Rule
-
Git refuses to check out the same branch in two worktrees
simultaneously. This prevents conflicting working-tree states. The
branch can exist in only one worktree's HEAD at a time.
- Detached HEAD in a Worktree
-
A worktree created with
--detach or checked out to a
specific commit (not a branch). Commits made here are only reachable
via the reflog until a branch is created. Useful for reviewing PRs,
bisecting, or debugging CI failures at a specific commit.
- Prunable Worktree
-
A worktree whose directory has been deleted (e.g., via
rm -rf) but whose metadata still exists in
.git/worktrees/. Shown in
git worktree list with the "prunable" annotation. Cleaned
up with git worktree prune.
- Control Tower (Pattern)
-
The main worktree kept on the
main branch, always clean,
used as the integration, merge, and coordination point. All other
worktrees are temporary — created for a task, removed when done. The
main worktree is the one long-running exception.
Danger Zone
- Rebase Across Worktrees
-
Rebasing a branch that is checked out in another worktree causes that
worktree's HEAD to diverge. The affected worktree must be reset with
git reset --hard <branch> to realign. Prevention:
remove the worktree before rebasing its branch, or coordinate.
rm -rf on a Worktree-
Deleting a worktree directory manually orphans the metadata in
.git/worktrees/. The branch may still be marked as
"checked out" and you'll get errors trying to check it out elsewhere.
Always use git worktree remove instead. Recovery:
git worktree prune.