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

1. Location Strategy

Keep worktrees outside main repo

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

1. 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

1. 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 -b

Create worktree from existing branch

git worktree add

List all worktrees

git worktree list

Remove worktree

git worktree remove

Clean up stale references

git worktree prune

Move worktree to different location

git worktree move

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

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