Git Worktrees Explained
Who is this for (1)
- Stakeholder Persona: Lead Developer — Written for the Lead Developer reader.
Git worktrees are the technology that enables Spec Kitty’s parallel development model. This document explains what worktrees are, why Spec Kitty uses them, and how they work in the modern lane-based execution model.
Naming note: a lane worktree path embeds
mid8— the first 8 characters of the mission’s ULIDmission_id, as in.worktrees/my-feature-01J6XW9K-lane-a/— only when the recorded Mission slug itself embeds a mid8. Lane naming keys on the recorded Mission slug and lane id alone; the Mission identity is never an input to it (see ADR2026-09-26-2and Execution Lanes §Naming). The legacy numeric-prefix form.worktrees/001-my-feature-lane-a/shown in some examples below still resolves for pre-083 projects. See the mission identity migration runbook for upgrade steps.
What is a Git Worktree?
A git worktree is a linked working directory that lets you check out multiple branches simultaneously, each in its own directory. Unlike cloning a repository multiple times, all worktrees share the same .git directory and repository history.
Normal git workflow (one branch at a time):
# You can only have one branch checked outgit checkout feature-a# To work on feature-b, you must switch branchesgit checkout feature-b # Now you're on feature-b, feature-a is goneWith worktrees (multiple branches simultaneously):
# Main repo stays on main branchmy-repo/ # main branch
# Each worktree has its own branch.worktrees/feature-a/ # feature-a branch.worktrees/feature-b/ # feature-b branchYou can now have three terminal windows open, each in a different directory, each on a different branch, all editing the same repository.
Why Does Spec Kitty Use Worktrees?
Parallel Development Without Branch Switching
Without worktrees, only one developer (or agent) can work at a time because git only allows one branch checked out per repository. With worktrees:
- Agent A works in
.worktrees/feature-lane-a/on the WPs assigned to lane A - Agent B works in
.worktrees/feature-lane-b/on the WPs assigned to lane B - Agent C works in
.worktrees/feature-lane-c/on the WPs assigned to lane C
All three agents work simultaneously, each with their own files, their own uncommitted changes, and their own branch.
Each Execution Lane Gets an Isolated Workspace
Problems with shared workspaces:
- Agent A edits
config.py, breaks it - Agent B (working on unrelated task) tries to run tests—they fail
- Both agents are now debugging each other’s problems
With lane-based execution workspaces:
- Agent A’s broken
config.pyonly exists in lane A’s workspace - Agent B’s workspace has clean files
- Isolation prevents cross-contamination
Multiple Agents Can Work Simultaneously
Spec Kitty’s parallel model requires:
- Multiple independent branches
- Multiple independent working directories
- Shared repository history (for merging later)
Git worktrees provide all three.
How Worktrees Work
The .git Directory
When you clone a repository, git creates a .git directory containing:
- All commits
- All branches
- All tags
- Repository configuration
A worktree doesn’t duplicate this. Instead, it creates a small file that points back to the main .git directory.
my-repo/├── .git/ # The real git database├── src/ # Your source files├── .worktrees/│ ├── feature-lane-a/│ │ ├── .git # Just a pointer file│ │ └── src/ # Separate copy of source files│ └── feature-lane-b/│ ├── .git # Just a pointer file│ └── src/ # Another separate copyWhat Worktrees Share
All worktrees share:
- Commit history (all commits are in one place)
- Branch definitions (branches exist in main
.git) - Configuration (global git settings)
- Remote references (origin, upstream, etc.)
What Worktrees Don’t Share
Each worktree has its own:
- Working directory (files on disk)
- Index (staging area)
- Current HEAD (which commit is checked out)
- Uncommitted changes
This means Agent A can have uncommitted changes to config.py without affecting Agent B’s config.py.
Cross-Mission Concurrency Is a Different Question
Worktree isolation covers lanes within one mission — each lane worktree
has its own HEAD, index, and working directory, so parallel WPs in the same
mission cannot collide. It does not cover two different missions
sharing the same primary checkout. Mission-lifecycle commands (mission create, status commits, move-task, backfill-topology) run against the
primary checkout’s HEAD, branch, and index — the same ones every worktree’s
.git file ultimately points back to — and there is no cross-mission lock
around those mutations. Two mission drivers issuing git operations from the
same primary checkout at the same time can interleave commits onto each
other’s branch tips or strand commits on the wrong branch.
mission create also cannot be run from inside a worktree, so a second
concurrent mission cannot cleanly sidestep the primary checkout that way. If
you need two missions active at once, use a separate clone (its own
.git) for the second mission rather than assuming worktrees provide
enough isolation — worktree isolation is per-lane-within-a-mission, not
per-mission.
Worktrees vs. Cloning
| Aspect | Worktree | Clone |
|---|---|---|
| Repository data | Shared | Duplicated |
| Disk space | Minimal | Full copy |
| Branches | Shared | Independent |
| Fetching/pushing | Once for all | Once per clone |
| Merging between | Direct (same repo) | Requires remote |
| Independence | Partial | Complete |
Use worktrees when:
- Working on the same project
- Need to merge branches together later
- Want to minimize disk usage
Use clones when:
- Working on different projects
- Complete isolation is required
- May never merge together
Git Commands for Worktrees
List All Worktrees
git worktree listExample output:
/path/to/my-repo abc1234 [main]/path/to/my-repo/.worktrees/feature-lane-a def5678 [feature-lane-a]/path/to/my-repo/.worktrees/feature-lane-b ghi9012 [feature-lane-b]Create a New Worktree
# Create worktree with existing branchgit worktree add .worktrees/feature-lane-a feature-lane-a
# Create worktree and create new branchgit worktree add -b feature-lane-a .worktrees/feature-lane-a
# Create worktree from specific commit/branchgit worktree add -b feature-lane-b .worktrees/feature-lane-b feature-lane-aRemove a Worktree
# Clean removal (worktree must be clean)git worktree remove .worktrees/feature-lane-a
# Force removal (discards uncommitted changes)git worktree remove --force .worktrees/feature-lane-aClean Up Stale Worktrees
# Prune worktrees whose directories no longer existgit worktree pruneWorktree Vocabulary
| Checkout | What it holds | Disposable? |
|---|---|---|
| Repository root checkout | The operator’s working copy; for a default Mission before settlement, the write checkout on the topic branch | No |
| Write checkout | The one checkout a single_branch Mission writes code and status into | No while a WP is in_progress |
Lane worktree (.worktrees/<slug>-lane-<id>) | One code lane’s branch; no status files | Yes: consolidate removes it as its last step |
| Coordination worktree | The coordination branch, where status is written | Yes: torn down with the coordination branch and marker as one unit |
Merge scratch worktree (.kittify/runtime/merge/<id>/workspace) | Consolidation’s internal scratch tree | Always cleaned up |
Status is never read from a lane worktree. Every reader goes through the one status read door (status/read_surface.py::resolve_status_read, ADR 4.x 2026-11-06-2); from the CLI, use spec-kitty agent tasks status.
Lane checkouts hide status
A lane worktree is a full checkout except for the Mission’s status.events.jsonl and status.json, which a managed sparse exclusion keeps out. Every new lane checkout gets it from lanes/lane_checkout.py::open_lane_checkout. Isolation of code is otherwise enforced by lane computation, ownership metadata, workspace context and consolidation guards, and agents stay inside the files owned by the active WP and lane.
Lane worktrees that already exist are brought in line by the clone-local migration 4.0.0rc8_lane_checkout_status_exclusion (run by spec-kitty upgrade). It finds them through the git worktree registry and reports one outcome per worktree:
| Outcome | Meaning |
|---|---|
excluded | A clean copy; the exclusion is applied and the files leave the disk |
flagged_redundant | A dirty copy whose every event is already on the status surface; the exclusion is applied and git keeps the modified file on disk |
refused_lane_only_events | A dirty copy holding events found nowhere else; the worktree is left untouched and the event ids are reported |
skipped_mid_operation | A merge, rebase or cherry-pick is in progress |
already_excluded | Nothing to do |
skipped_legacy_mission | A genuinely-legacy Mission (no coordination branch, no stored topology, not flattened) writes its status into the lane checkout, so the lane is left untouched |
While any lane is refused_lane_only_events or skipped_mid_operation, the migration is skipped and selected again on the next upgrade. spec-kitty doctor sparse-checkout reports each such lane as LANE_STATUS_NOT_EXCLUDED with its remedy: for lane-only events, record each transition on the status surface with spec-kitty agent tasks move-task, discard the lane copy’s change to the two status files, then run spec-kitty upgrade.
Consolidate reads git state through a run-scoped cache
A consolidation run asks git the same questions many times across the repository root checkout, the coordination worktree and the lane worktrees. Examples are which branch a checkout holds, which worktree holds a branch, a branch’s tip, and the remote’s default branch. Since #7689, spec-kitty consolidate answers repeats from a cache that lives only for that one run (kernel/git/read_cache.py, entered by run_consolidate). No other command turns it on, and outside the run every read spawns git as before.
What decides whether an answer is reused. Each cached read declares which git files its answer depends on: one ref, the checkout’s HEAD, the repository config, or, for git worktree list, the whole metadata tree. Before reusing an answer, the cache re-reads those files’ bytes without spawning git. It reuses the answer only if the bytes are identical, comparing content and never timestamps. Any ref update, branch switch, worktree add or remove, config write or pack-refs therefore changes the bytes and forces git to run again, whoever made the change.
What may be cached. Only a read whose answer is a pure function of git metadata files may use the cache. Never cache a read of the working tree or the index (git status, git diff, file contents): their answer is not in the files the cache watches.
When the cache stands aside. Every read runs uncached, exactly as without the cache, in these cases:
- outside a consolidate run;
- when a
GIT_DIR,GIT_COMMON_DIR,GIT_WORK_TREE,GIT_NAMESPACE,GIT_OBJECT_DIRECTORYorGIT_CONFIGvariable redirects git; - when the repository cannot be located from the read’s directory;
- when the repository stores refs in reftable (
extensions.refStorage = reftable), whose layout the cache does not model yet.
Safety-relevant reads. Rollback’s read of a branch’s live tip may be answered from the cache, but the restore itself is a compare-and-swap update-ref: git, not the cache, enforces the expected old value. A failed lookup of the remote’s default branch (an unreachable remote) is never stored, so the next protection-policy resolution asks again.
Common Issues
“Worktree already exists”
Error:
fatal: 'feature-lane-a' already has a worktree at '.worktrees/feature-lane-a'Cause: You’re trying to create a worktree for a branch that’s already checked out somewhere.
Solution:
# Find where it's checked outgit worktree list
# Either remove the existing worktreegit worktree remove .worktrees/feature-lane-a
# Or use that existing worktree insteadcd .worktrees/feature-lane-a“Branch is already checked out”
Error:
fatal: 'feature-lane-a' is already checked out at '/path/to/other/worktree'Cause: Git won’t let two worktrees have the same branch checked out.
Solution:
# Find the other worktreegit worktree list
# Remove it if not neededgit worktree remove /path/to/other/worktree
# Or work in the existing worktreecd /path/to/other/worktreeCleanup After Crashes
If Spec Kitty or your system crashes mid-operation, worktrees may be left in an inconsistent state.
Symptoms:
git worktree listshows non-existent directories- Errors about locked worktrees
- Can’t create new worktrees
Solution:
# Clean up stale worktree referencesgit worktree prune
# Force unlock if neededgit worktree unlock .worktrees/stuck-worktree
# Verify cleanupgit worktree listHEAD Detached in Worktree
Symptom: Commits in worktree aren’t on any branch.
Cause: Worktree was created from a commit, not a branch.
Solution:
cd .worktrees/my-feature-01J6XW9K-lane-agit checkout -b kitty/mission-my-feature-01J6XW9K-lane-a # Create and switch to branchFurther Reading
- Git Worktree Documentation - Official git documentation
See Also
- Execution Lanes - How Spec Kitty uses worktrees
- Branch-Target Routing - Where each diff type lands (planning, status, code, docs) and the simple-case flat collapse when no lanes are configured
- Spec-Driven Development - The methodology that requires parallel work
- Kanban Workflow - How work progresses through lanes
This document explains git worktrees for understanding. For practical steps in Spec Kitty, see the how-to guides.