managing-worktree-recipe

Git Worktree Management

Quick Reference

Create → Work → Cleanup

git worktree add ../repo-feature feature/VC-1234-desc
cd ../repo-feature
git worktree remove ../repo-feature
git worktree prune

When to Use

Multiple branches simultaneously | PR reviews in isolation | Context switching | Parallel feature development

Core Operations

creating-worktrees.md:

add <path> <branch> → new worktree
-b → create branch | existing branch → checkout

managing-worktrees.md:

list → all worktrees + status
lock/unlock → prevent removal
move → relocate path

cleanup-worktrees.md:

remove <path> → delete worktree
prune → clean stale refs

git-integration.md:

Branch naming: feature/VC-1234-desc (github-recipe compatible)
PR checkout: gh pr checkout + worktree

Worktree Basics

WT = worktree (abbreviation used throughout)

git worktree add <path> <committish>
git worktree add ../repo-feature feature/VC-1234-desc
git worktree add ../repo-fix -b fix/VC-5678-bug origin/main

Structure:

project/
├── .git/                    # shared git dir
├── repo/                    # main WT (HEAD)
├── repo-feature/            # feature WT
└── repo-fix/                # fix WT

Naming Conventions

Pattern	Format	Example
Path	../repo-{type}	../repo-feature
Path with ticket	../repo-{ticket}	../repo-VC-1234
Path descriptive	../repo-{desc}	../repo-auth-fix

Consistency with branch:

Branch: feature/VC-1234-add-auth
Path: ../repo-VC-1234 OR ../repo-auth

Common Commands

Create WT:

git worktree add <path> <branch>                    # existing branch
git worktree add <path> -b <new-branch> <base>     # new branch
git worktree add ../repo-pr -b pr-review origin/pr-branch

List WT:

git worktree list
git worktree list --porcelain                       # parseable

Output:

/Users/dev/project           abc1234 [main]
/Users/dev/project-feature   def5678 [feature/VC-1234-desc]
/Users/dev/project-fix       ghi9012 [fix/VC-5678-bug]

Remove WT:

git worktree remove <path>
git worktree remove ../repo-feature
git worktree remove --force <path>                  # uncommitted changes

Cleanup:

git worktree prune                                  # remove stale refs
git worktree prune --dry-run                        # preview

Status Operations

List all:

git worktree list

Navigate:

cd $(git worktree list | grep 'feature' | awk '{print $1}')

Current WT:

pwd
git branch --show-current

Branch Operations

Create + WT:

git fetch origin main
git worktree add ../repo-VC-1234 -b feature/VC-1234-desc origin/main
cd ../repo-VC-1234

Existing branch:

git fetch origin
git worktree add ../repo-existing feature/VC-1234-desc

Error handling:

"already exists" → git worktree remove old | choose new path
"already checked out" → different branch per WT (MANDATORY)
"uncommitted changes" → --force (destructive) | commit first

Lock/Unlock

Prevent removal:

git worktree lock <path>                            # prevent remove
git worktree lock <path> --reason "In use by CI"
git worktree unlock <path>

Use cases:

Network drive → lock | Shared WT → lock | Automated cleanup → locked WTs skip

Move Operations

Relocate WT:

git worktree move <source> <destination>
git worktree move ../repo-old ../repo-new

Limitations:

Main WT → cannot move
Locked WT → unlock first

Integration Patterns

With github-recipe:

git worktree add ../repo-VC-1234 -b feature/VC-1234-desc origin/main
cd ../repo-VC-1234

git commit -m "feat(VC-1234): implement feature"
pnpm format && pnpm lint && pnpm test
git push -u origin feature/VC-1234-desc

gh pr create --title "feat(VC-1234): implement feature" --body-file PR.md

PR review:

gh pr list
gh pr checkout 123 --detach                         # detached HEAD
git worktree add ../repo-pr-123 FETCH_HEAD         # review in isolation
cd ../repo-pr-123
pnpm test
cd ../repo
git worktree remove ../repo-pr-123

Multiple repos:

for repo in api frontend; do
  cd $repo
  git worktree add ../${repo}-VC-1234 -b feature/VC-1234-sync origin/main
done

Cleanup Patterns

Remove single:

cd ../repo
git worktree remove ../repo-feature

Remove stale:

git worktree prune

Force remove:

git worktree remove --force ../repo-dirty           # uncommitted changes

Manual cleanup:

rm -rf ../repo-old
git worktree prune

Validation

Check WT status:

git worktree list
ls -la .git/worktrees/

Verify branch:

cd <worktree-path>
git branch --show-current
git status

Common Issues

Error	Cause	Fix
"already exists"	Path occupied	Remove old WT | Choose new path
"already checked out"	Branch in another WT	Different branch | Remove other WT
"not a working tree"	Invalid path	Check path | git worktree list
"uncommitted changes"	Dirty WT	Commit | Stash | --force
"main worktree"	Cannot move main	Only secondary WTs moveable

Stale refs:

git worktree prune --dry-run                        # check first
git worktree prune                                  # cleanup

Workflow Validation (Execute After Operations)

MANDATORY: Run after WT creation/removal.

Phase	Action
1. Execute	Create/remove/cleanup WT
2. Validate	Review conversation context for compliance
3. Report	✓ Pass → Done | ✗ Fail → List violations with evidence
4. Fix	Violations found → Correct → Re-validate

Validation method:

Review conversation tool calls (NOT re-run commands)
→ Verify WT operations occurred
→ Check branch naming (feature/VC-1234-desc)
→ Cite tool call evidence

Validation checks:

Check	Required Evidence in Conversation	Pass	Fail
Create command	Exact: git worktree add <path> -b <branch> origin/main	Uses -b flag pattern (line 151)	Missing -b | Wrong base | Tracks remote
Branch tracking	Command creates NEW branch from base	Independent branch	Tracks origin/main | Checkout existing
Path pattern	../repo-{ticket|desc}	Matches convention	Wrong pattern
Branch format	(feature|fix|chore)/XXX-####-desc	Compliant	Non-compliant
Integration	github-recipe workflow if commit/push	Followed	Skipped
Cleanup	Prune after removals	Executed	Missing

Output format:

VALIDATION REPORT:
✓ Create command: git worktree add ../repo-VC-1234 -b feature/VC-1234-add-auth origin/main
  [Evidence] Tool call: Bash command line 151 pattern with -b flag
✓ Branch tracking: NEW branch from origin/main (independent)
  [Evidence] Command creates branch, not checkout existing
✓ Path pattern: ../repo-VC-1234 matches ../repo-{ticket}
✓ Branch format: feature/VC-1234-add-auth compliant
✓ Git integration: Followed github-recipe for commit/push
✓ Cleanup: Prune executed

ALL CHECKS PASS ✓

Example with violation:

VALIDATION REPORT:
✗ FAIL: Create command missing -b flag
  [Evidence] Used: git worktree add ../repo-VC-1234 feature/VC-1234-desc
  [Required] git worktree add ../repo-VC-1234 -b feature/VC-1234-desc origin/main
✗ FAIL: Branch incorrectly tracks origin/main
  [Evidence] Command checked out existing branch instead of creating new
  [Impact] Branch will track remote instead of being independent
✗ FAIL: No prune after WT removal

VIOLATIONS (3):
1. Create command: Must use -b flag pattern from line 151
2. Branch tracking: Creates NEW branch from base, not checkout existing
3. Missing cleanup: Run git worktree prune after removal

ACTION: Fix violations and re-validate

Re-validation required after fixes. Repeat until ALL checks pass.