worktrees.md

Git Worktrees for Parallel Development

Worktrees let you work on multiple branches simultaneously in different directories.

The Problem

# You're working on feature-a
# Suddenly need to fix a bug on main
# Options:
# 1. Stash changes (messy)
# 2. Commit WIP (ugly history)
# 3. Clone repo again (slow, uses disk space)

The Solution: Worktrees

# Create a worktree for hotfix
git worktree add ../hotfix main

# Now you have:
# /project          <- feature-a branch
# /hotfix           <- main branch

# Work on hotfix without touching feature-a!

Basic Commands

# Add worktree for existing branch
git worktree add ../bugfix bugfix-branch

# Add worktree with new branch
git worktree add -b new-feature ../new-feature main

# List all worktrees
git worktree list

# Remove worktree
git worktree remove ../hotfix

# Prune stale worktrees
git worktree prune

Use Cases

1. Hotfixes While Working on Features

git worktree add ../hotfix main
cd ../hotfix
# fix bug, commit, push
cd ../project
git worktree remove ../hotfix

2. Comparing Branches Side by Side

git worktree add ../v1 release/v1
git worktree add ../v2 release/v2
# Open both in different IDE windows

3. Running Tests on Different Branches

git worktree add ../test-main main
cd ../test-main && npm test

Benefits

• No stashing needed
• Faster than cloning
• Shared .git directory (saves disk space)
• Clean mental separation

---

Learned: December 20, 2025 Tags: Git, Worktrees, Productivity