Git Worktree Management
Iron Law
NEVER MODIFY FILES IN A WORKTREE YOU DID NOT CREATE
Operations
1. Create
Create a new worktree for isolated parallel development.
git worktree add <path> -b <branch-name>- Always use a descriptive branch name matching the worktree purpose
- Place worktrees in a consistent location (e.g.,
/tmp/<repo>-worktrees/<name>) - Verify the worktree was created successfully before proceeding
- Initialize any required workspace files (progress.txt, CLAUDE.md, prd.json)
2. List
Show all active worktrees and their branches.
git worktree list- Check for stale or orphaned worktrees
- Verify each worktree points to a valid path
- Note which branches are checked out where
3. Switch
Navigate between worktrees safely.
- Always verify your current working directory before making changes
- Use absolute paths to avoid confusion
- Check
git statusin the target worktree before starting work - Never assume you are in the correct worktree — verify with
pwdandgit branch
4. Sync
Keep worktrees up to date with upstream changes.
# From within the worktree:
git fetch origin
git rebase origin/main # or merge, depending on strategy- Resolve conflicts in the worktree where they occur
- Do not sync during active implementation — finish the current story first
- After syncing, re-run quality checks to catch integration issues
5. Cleanup
Remove worktrees that are no longer needed.
git worktree remove <path>
git worktree prune- Verify all changes are committed and pushed before removing
- Never force-remove a worktree with uncommitted changes
- Prune stale references after removal
- Delete the associated branch only after confirming the merge
Red Flags — If You Catch Yourself Thinking:
| Thought | Reality |
|---|---|
| "I'll just edit files in this other worktree quickly" | Each worktree is an isolated workspace. Switch properly or create a new one. |
| "I don't need to check which worktree I'm in" | Wrong worktree = wrong branch = wrong commits. ALWAYS verify with pwd and git branch. |
| "I'll force-remove this worktree to save time" | Force-remove destroys uncommitted work. Check git status first. |
| "Pruning is optional, I'll do it later" | Stale worktree references cause confusing errors. Prune after every removal. |
Rules
- Always verify your working directory before making any changes
- Never force-remove a worktree without checking for uncommitted changes
- Prune stale worktree references after every removal
- Use absolute paths for all worktree operations
- One branch per worktree — never checkout a branch that is active in another worktree