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.