git-worktrees

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>