Git Worktree

Trigger

• Keywords: worktree, parallel development, simultaneous branches, work directory, checkout another branch

When NOT to Use

• Only need to switch branches (use git checkout)
• Need a fully independent repo copy (use git clone)
• Temporarily view a single file (use git show branch:file)

Core Concept

┌─────────────────────────────────────────────────┐
│              .git (shared object database)        │
│         commits / blobs / trees / refs           │
├────────────┬────────────┬────────────────────────┤
│ repo/      │ ../wt-A/   │ ../wt-B/               │
│ (main)     │ (feat/A)   │ (feat/B)               │
│ HEAD       │ HEAD       │ HEAD                   │
│ index      │ index      │ index                  │
│ files      │ files      │ files                  │
└────────────┴────────────┴────────────────────────┘

Property	Description
Shared objects	All worktrees share the same commit/blob/tree store
Independent HEAD	Each worktree has its own HEAD and index
Branch exclusive	Same branch cannot be checked out in two worktrees
Shared commits	Commits from any worktree appear in the same history

Naming Convention

~/Project/
├── my-repo/                    # Main repo (main or dev branch)
├── wt-{repo}-hotfix/           # worktree: hotfix
├── wt-{repo}-feat-gas/         # worktree: feature/gas
└── wt-{repo}-review-pr-123/    # worktree: PR review

Format: wt-{repo-shortname}-{purpose}, placed in the same parent directory as the repo.

Workflow

Create Worktree

# 1. Checkout existing branch
git worktree add ../wt-{repo}-hotfix fix/hotfix-123

# 2. Create new branch and checkout (from main)
git worktree add -b feat/new-feature ../wt-{repo}-new-feat main

# 3. Detach mode (temporarily view tag/commit)
git worktree add --detach ../wt-{repo}-review v1.2.3

Daily Operations

# List all worktrees
git worktree list

# Enter worktree and work normally
cd ../wt-{repo}-hotfix
git status
git commit -am "fix: ..."
git push -u origin fix/hotfix-123

# Return to main repo
cd ../my-repo

Cleanup Worktree

# Recommended: use git command to remove
git worktree remove ../wt-{repo}-hotfix

# If directory was manually deleted
git worktree prune

# Lock to prevent accidental deletion (long-lived worktrees)
git worktree lock ../wt-{repo}-hotfix
git worktree unlock ../wt-{repo}-hotfix

# Move worktree path
git worktree move ../wt-old ../wt-new

Common Scenarios

Scenario	Action
Develop two features simultaneously	Create a worktree for each, checkout respective branches
Hotfix without affecting current work	git worktree add ../wt-hotfix fix/xxx
Review PR without switching branch	git worktree add ../wt-review-123 origin/feat/xxx
Run tests on old version	git worktree add --detach ../wt-test v1.0.0
Compare two versions	Open two worktrees, each checking out different tags

Common Errors

Error	Cause	Solution
branch is already checked out	Branch is in use by another worktree	Create new branch or use --detach
is not a valid directory	Worktree directory was manually deleted	git worktree prune
.claude config not in worktree	.claude/ is gitignored (local-only)	Auto-synced on add; run sync script manually if needed

.claude/ Auto-Sync

After git worktree add, the sync script (scripts/worktree-claude-sync.sh) automatically recreates .claude/ in the new worktree:

Entry	Strategy	Notes
agents, commands, hooks, rules, scripts, skills	Symlink (../<dir>)	Points to worktree's own tracked dirs
CLAUDE.md	Symlink (../CLAUDE.md)	Points to worktree's tracked root file
.gitignore	Copy	Isolated per worktree
settings.local.json	Copy	Isolated (contains absolute paths)
cache/, .git/	Skip	Per-worktree, auto-created

Opt-out: Use --no-claude-sync to skip.

Existing .claude/: If .claude/ already exists in the worktree (user-managed), sync is skipped.

Verification

• git worktree list shows correct worktrees
• Worktree directory can git status normally
• .claude/ exists in worktree with correct symlinks
• Claude Code loads hooks/rules/skills normally in worktree
• After completion, clean up with git worktree remove

References

• references/commands.md — Command quick reference

Examples

Parallel Development + Hotfix

Input: I need to continue developing gas-account while fixing a hotfix
Action:
  1. git worktree add -b fix/hotfix-456 ../wt-{repo}-hotfix main
  2. cd ../wt-{repo}-hotfix → fix → commit → push
  3. git worktree remove ../wt-{repo}-hotfix

Review PR

Input: Checkout PR #123 branch to review
Action:
  1. git fetch origin pull/123/head:pr-123
  2. git worktree add ../wt-{repo}-pr-123 pr-123
  3. cd ../wt-{repo}-pr-123 → review/test
  4. git worktree remove ../wt-{repo}-pr-123

Run Tests on Old Version

Input: Run tests on v1.0.0
Action:
  1. git worktree add --detach ../wt-{repo}-test v1.0.0
  2. cd ../wt-{repo}-test → run tests
  3. git worktree remove ../wt-{repo}-test