Worktrees

Why it matters

Ever needed to check something on another branch without losing your current work? Worktrees let you have multiple branches checked out simultaneously in different directories.

Key concepts

• Worktree — Additional working directory linked to same repository
• git worktree add — Create new worktree for a branch
• git worktree list — Show all worktrees for this repository
• Parallel Development — Working on multiple branches simultaneously

The idea

The Multiple Desks Analogy

Imagine you’re working on a complex project at your desk. Papers are spread everywhere—you’re in the middle of something important.

Suddenly, your boss asks you to quickly review yesterday’s report. With a single desk, you’d have to:

1. Stack all your papers neatly (git stash)
2. Pull out yesterday’s papers
3. Review them
4. Put them away
5. Unstack your original papers (git stash pop)

With multiple desks (worktrees):

1. Walk to another desk that already has yesterday’s papers
2. Review them
3. Walk back to your original desk—nothing moved

How Worktrees Work

~/projects/myapp/           # Main worktree (main branch)
~/projects/myapp-feature/   # Feature worktree (feature/login branch)
~/projects/myapp-hotfix/    # Hotfix worktree (hotfix/security branch)

All three share the same .git database but have separate working directories. No stashing. No lost context. No commit-before-switching.

Walkthrough

Creating Worktrees

# Create worktree for existing branch
git worktree add ../myapp-feature feature/login

# Create worktree with new branch
git worktree add -b hotfix/urgent ../myapp-hotfix main

# Create worktree at specific commit
git worktree add ../myapp-v1 v1.0.0

Managing Worktrees

# List all worktrees
git worktree list

# Output:
# /home/user/myapp         abc123 [main]
# /home/user/myapp-feature def456 [feature/login]
# /home/user/myapp-hotfix  ghi789 [hotfix/urgent]

# Remove worktree (after deleting directory)
rm -rf ../myapp-hotfix
git worktree prune

# Or remove directly
git worktree remove ../myapp-hotfix

# Lock worktree (prevent accidental deletion)
git worktree lock ../myapp-feature
git worktree unlock ../myapp-feature

Use Cases

1. Quick Bug Fix While Developing

# You're on feature branch, need to fix production bug
git worktree add -b hotfix/crash ../hotfix main
cd ../hotfix
# Fix bug, commit, push, PR
cd ../myapp
git worktree remove ../hotfix
# Continue feature work—nothing was disturbed

2. Reviewing Pull Requests

# Check out PR branch for testing
git fetch origin pull/123/head:pr-123
git worktree add ../pr-review pr-123
cd ../pr-review
# Test, review, comment
git worktree remove ../pr-review

3. Comparing Versions

# Check out old version for comparison
git worktree add ../v1-reference v1.0.0
# Now you can diff, test, or run both versions simultaneously

4. Long-Running Tasks

# Build takes 30 minutes? Keep working on another branch
git worktree add ../myapp-build main
cd ../myapp-build
make release &
cd ../myapp
# Continue development while build runs

Worktrees vs Alternatives

Scenario	Worktree	Stash	Clone
Quick branch switch	✅ Instant	⚠️ Slower	❌ Slow
Parallel branches	✅ Easy	❌ Not possible	✅ Possible
Shared history	✅ Yes	✅ Yes	⚠️ Separate
Disk space	✅ Minimal	✅ None	❌ Full copy
Complexity	⚠️ Medium	✅ Low	⚠️ Medium

Key takeaways

• Worktrees = multiple branches checked out simultaneously
• Share same .git database, minimal disk space
• No stashing or committing required to switch context
• Perfect for hotfixes, PR reviews, comparisons

Dos & don’ts

✅ DO

• Use for context switching: Hotfixes while developing features
• Use for PR reviews: Test branches without disrupting work
• Clean up after yourself: Remove worktrees when done
• Lock important worktrees: Prevent accidental removal

❌ DON’T

• Don’t checkout same branch in multiple worktrees: Git prevents this
• Don’t forget to prune: git worktree prune cleans stale entries
• Don’t leave worktrees forever: They can get stale and confusing

Going deeper

Bare repositories with worktrees: Advanced setup: Clone as bare repo, add worktrees for each branch. git clone --bare repo.git .bare git worktree add main main All branches are worktrees, no “main” working directory.

IDE support: Most IDEs handle worktrees well—each worktree opens as a separate project. VSCode, IntelliJ, and others recognize worktree structure.

Common mistakes

Same branch in multiple worktrees: Git prevents this because it would cause confusion—which worktree’s changes win? If you need this, one worktree should be detached HEAD.

Forgetting worktrees exist: git worktree list shows all worktrees. Check periodically and clean up stale ones.