git-worktrees

name	git-worktrees
description	Work with git worktrees for isolated parallel development. Use when starting feature work in isolation, when need separate workspace without branch switching, or when cleaning up worktrees after PR merge.

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>