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: '' 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