Git Worktrees

Git Worktrees

Overview

Git worktrees allow you to have multiple working directories from the same repository, each with a different branch checked out. Work on multiple branches simultaneously without switching.

When to Use Worktrees

✅ Perfect For:

• Stacked PR development (one worktree per PR)
• Urgent hotfix while working on feature
• Parallel development on multiple features
• Code review in isolation
• Testing cross-branch interactions
• Running multiple dev servers simultaneously

⚠️ Consider Alternatives When:

• Limited disk space (worktrees duplicate working directory)
• Simple branch switching is sufficient
• Only working on one branch at a time

Basic Workflow

Create Worktree

New Branch:

# Create worktree with new branch
git worktree add ../​worktrees/​feature-auth -b feature/​authentication

# Navigate to worktree
cd ../​worktrees/​feature-auth

Existing Branch:

# Create worktree from existing remote branch
git worktree add ../​worktrees/​feature-profile feature/​user-profile

# Or from origin
git worktree add ../​worktrees/​review origin/​feature/​pr-to-review

List Worktrees

git worktree list

# Output:
# /​Users/​dev/​project              abc123 [main]
# /​Users/​dev/​worktrees/​f-auth     def456 [feature/​authentication]
# /​Users/​dev/​worktrees/​f-profile  ghi789 [feature/​user-profile]

Remove Worktree

# Remove worktree (deletes directory)
git worktree remove ../​worktrees/​feature-auth

# Or manually delete directory and prune
rm -rf ../​worktrees/​feature-auth
git worktree prune

Directory Structure

Recommended layout:

/​Users/​dev/
├── my-project/              # Main repository
│   ├── .git/               # Git database
│   ├── src/
│   └── ...
└── my-project-worktrees/    # All worktrees here
    ├── feature-auth/       # feature/​authentication branch
    ├── feature-profile/    # feature/​user-profile branch
    ├── hotfix-urgent/      # hotfix/​urgent-fix branch
    └── review-pr-123/      # Reviewing PR #123

Use Case: Stacked PRs

Perfect for stacked PR workflow - one worktree per PR:

# Create worktree for each PR in stack
git worktree add ../​stack/​pr-001 -b feature/​001-base-auth
git worktree add ../​stack/​pr-002 -b feature/​002-user-profile
git worktree add ../​stack/​pr-003 -b feature/​003-admin-panel

# Work in each independently
cd ../​stack/​pr-001
# Implement base auth
git commit -am "feat: base authentication"
git push -u origin feature/​001-base-auth

cd ../​stack/​pr-002
# Already on feature/​002-user-profile branch
# Implement user profile (depends on pr-001)
git commit -am "feat: user profile with auth"
git push -u origin feature/​002-user-profile

cd ../​stack/​pr-003
# Implement admin panel (depends on pr-002)
git commit -am "feat: admin panel"
git push -u origin feature/​003-admin-panel

Use Case: Parallel Development

Run multiple dev servers simultaneously:

# Terminal 1: Main feature development
cd /​project-worktrees/​feature-new-ui
npm install
npm run dev  # Server on port 3000

# Terminal 2: Urgent hotfix (different branch)
cd /​project-worktrees/​hotfix-critical
npm install
npm run dev -- --port 3001  # Server on port 3001

# Both running simultaneously without branch switching

Use Case: Code Review

Review PRs in isolation:

# Create worktree for PR review
git worktree add ../​review/​pr-456 origin/​feature/​user-auth

cd ../​review/​pr-456
npm install
npm test
npm run dev

# Review code, test functionality
# When done, remove worktree
cd /​main-project
git worktree remove ../​review/​pr-456

Updating Stacked PRs with Worktrees

When base PR changes, update chain across worktrees:

# PR-001 got feedback
cd /​stack/​pr-001
git pull origin feature/​001-base-auth
# Make changes, push

# Update PR-002 (in separate worktree)
cd /​stack/​pr-002
git rebase feature/​001-base-auth
git push --force-with-lease origin feature/​002-user-profile

# Update PR-003 (in separate worktree)
cd /​stack/​pr-003
git rebase feature/​002-user-profile
git push --force-with-lease origin feature/​003-admin-panel

Managing Dependencies

Shared node_modules (Save Disk Space)

Option 1: Symlink

cd /​worktrees/​feature-auth
ln -s /​main-project/​node_modules node_modules

Option 2: Separate Install

cd /​worktrees/​feature-auth
npm install  # Independent node_modules

Trade-off:

• Symlink: Less disk space, may have version conflicts
• Separate: More disk space, guaranteed isolation

Best Practices

1. Naming Convention

# Use descriptive, consistent names
git worktree add ../​worktrees/​feature-authentication feature/​authentication
git worktree add ../​worktrees/​hotfix-security hotfix/​security-patch

2. Location Strategy

# Keep worktrees outside main repo
/​Users/​dev/​project/              # Main repo (never delete)
/​Users/​dev/​project-worktrees/    # All worktrees here (safe to delete)

3. Cleanup Discipline

# When PR merged, remove worktree immediately
git worktree remove path/​to/​worktree

# Periodically check for stale worktrees
git worktree prune

# Delete merged branches
git branch -d feature/​old-branch
git push origin --delete feature/​old-branch

4. One Branch Per Worktree

❌ WRONG: Switching branches in worktree defeats the purpose
✅ CORRECT: Each worktree permanently on one branch

Common Commands

# Create worktree with new branch
git worktree add <path> -b <branch>

# Create worktree from existing branch
git worktree add <path> <branch>

# List all worktrees
git worktree list

# Remove worktree
git worktree remove <path>

# Clean up stale references
git worktree prune

# Move worktree to different location
git worktree move <old-path> <new-path>

Troubleshooting

Issue: "fatal: '<branch>' is already checked out"

Cause: Branch is checked out in another worktree

Solution:

# List worktrees to find where branch is checked out
git worktree list

# Either work in existing worktree or remove it first
git worktree remove <path-to-old-worktree>

Issue: Disk space concerns

Solution:

• Use symlinks for node_modules
• Remove worktrees when PRs merged
• Run git worktree prune regularly
• Consider using sparse-checkout for large repos

Issue: IDE confusion with multiple worktrees

Solution:

• Open each worktree as separate workspace
• Use IDE's multi-window/​split-workspace features
• Name worktrees descriptively for easy identification

Agent Instructions

When delegating worktree setup to version-control agent:

Task: Create worktrees for stacked PR development

Requirements:
- Create 3 worktrees in /​project-worktrees/
- Worktree 1: pr-001 with branch feature/​001-base-auth
- Worktree 2: pr-002 with branch feature/​002-user-profile
- Worktree 3: pr-003 with branch feature/​003-admin-panel

Commands:
git worktree add ../​project-worktrees/​pr-001 -b feature/​001-base-auth
git worktree add ../​project-worktrees/​pr-002 -b feature/​002-user-profile
git worktree add ../​project-worktrees/​pr-003 -b feature/​003-admin-panel

Verification: git worktree list should show all 3 worktrees

Benefits

✅ No Branch Switching: Work on multiple branches without git checkout ✅ Parallel Servers: Run multiple dev environments simultaneously ✅ Preserve State: Build artifacts and node_modules stay per-branch ✅ Safer Reviews: Test PRs without affecting main working directory ✅ Faster Context Switch: Jump between worktrees instead of rebasing

Related Skills

• stacked-prs - Combine worktrees with stacked PR workflow
• git-workflow - General git branching patterns
• code-review - Review code in isolated worktrees