Git Worktrees
Overview
Git worktrees create isolated workspaces sharing the same repository, allowing
work on multiple branches simultaneously without switching. Each worktree is a
separate directory with its own working tree, but they share the same .git
history.
When to Use Worktrees
- Parallel development: Work on feature A while feature B builds/tests
- Code review: Check out PR branch without disrupting current work
- Experiments: Try something risky without affecting main workspace
- Long-running tasks: Keep main branch available while feature develops
Quick Reference
| Action | Command |
|---|---|
| List worktrees | git worktree list |
| Create worktree | git worktree add <path> -b <branch> |
| Create from existing branch | git worktree add <path> <branch> |
| Remove worktree | git worktree remove <path> |
| Prune stale worktrees | git worktree prune |
Creating Worktrees
New Feature Branch
# Create worktree with new branch
git worktree add .worktrees/my-feature -b feat/my-feature
# Or specify base branch
git worktree add .worktrees/my-feature -b feat/my-feature main
From Existing Branch
# Check out existing remote branch
git worktree add .worktrees/pr-review origin/fix-bug
# Check out existing local branch
git worktree add .worktrees/hotfix hotfix/urgent-fix
Directory Structure
project/
├── .git/ # Shared git history
├── .worktrees/ # Convention: keep worktrees here
│ ├── feature-a/ # First worktree
│ └── feature-b/ # Second worktree
└── src/ # Main worktree files
Setup After Creating Worktree
After creating a worktree, you typically need to:
cd .worktrees/my-feature
# Install dependencies
npm install # or pnpm install, yarn, etc.
# Copy any required env files
cp ../.env .env.local
# Verify setup
npm test
Safety Rules
NEVER remove a worktree with uncommitted changes without confirmation.
# Check for uncommitted changes first
git -C .worktrees/my-feature status --porcelain
# If empty, safe to remove
git worktree remove .worktrees/my-feature
# Delete the branch after merge (-d is safe, fails if not merged)
git branch -d feat/my-feature
Removal Decision Matrix
| PR Merged? | Uncommitted Changes? | Action |
|---|---|---|
| Yes | No | Safe to remove |
| Yes | Yes | Ask user - changes will be lost |
| No | No | Do NOT remove - work not preserved |
| No | Yes | Do NOT remove - active work |
Cleaning Up Worktrees
Manual Cleanup
# 1. Check if work is merged (if using GitHub)
gh pr list --head feat/my-feature --state merged
# 2. Check for uncommitted changes
git -C .worktrees/my-feature status --porcelain
# 3. Remove worktree (only if merged or confirmed with user)
git worktree remove .worktrees/my-feature
# 4. Delete branch
git branch -d feat/my-feature
Prune Stale Worktrees
If a worktree directory was deleted manually:
git worktree prune
Common Patterns
Review a PR
# Create worktree from PR branch
git fetch origin pull/123/head:pr-123
git worktree add .worktrees/pr-123 pr-123
# Review, test, then clean up
git worktree remove .worktrees/pr-123
git branch -D pr-123
Parallel Feature Development
# Main work continues in project root
# Start new feature in worktree
git worktree add .worktrees/new-api -b feat/new-api
# Work on both simultaneously
code .worktrees/new-api # Opens new VS Code window
Troubleshooting
"Branch already checked out"
A branch can only be checked out in one worktree at a time:
# Find where branch is checked out
git worktree list
# Remove that worktree first, or use different branch
"Worktree directory not empty"
# Force add if directory exists but isn't a worktree
git worktree add --force <path> <branch>
Locked Worktree
If a worktree is locked (prevents accidental removal):
# Unlock it
git worktree unlock <path>
# Then remove
git worktree remove <path>