Git worktrees: work on multiple branches simultaneously

You are deep in a feature branch when an urgent production bug comes in. You stash your work, switch branches, fix the bug, switch back, pop the stash — and spend the next ten minutes remembering where you were. Git worktrees eliminate this context switch entirely. Each worktree is a separate directory with its own branch checked out. You just open a new terminal window and go.

How worktrees work

A repository normally has one working tree: the directory containing your code. Worktrees let you create additional working directories, each with a different branch checked out, all sharing the same .git directory.

# Add a new worktree in a sibling directory for an existing branch
git worktree add ../myapp-hotfix hotfix/payment-crash

# Add a new worktree and create a new branch simultaneously
git worktree add ../myapp-feature -b feature/dark-mode

# List all worktrees
git worktree list

After these commands:

• ~/projects/myapp — your main worktree, on main
• ~/projects/myapp-hotfix — on hotfix/payment-crash
• ~/projects/myapp-feature — on feature/dark-mode

All three share the same .git directory. Changes committed in any worktree are immediately visible in the others via git log or git fetch.

The workflow for urgent interruptions

# You are in ~/projects/myapp on feature/payments, in the middle of something

# Create a hotfix worktree — no stashing needed
git worktree add ../myapp-hotfix -b hotfix/crash-fix origin/main

# Open the hotfix in a new terminal (or editor window)
cd ../myapp-hotfix
# Fix the bug, commit, push
git add .
git commit -m "fix: null check in payment processor"
git push origin hotfix/crash-fix

# Back in ~/projects/myapp — your feature branch is exactly as you left it
# No stash, no context loss

Worktrees with VS Code

Open each worktree as a separate VS Code window:

# Open the hotfix worktree in a new VS Code window
code ../myapp-hotfix

# Or add it to the current workspace
code --add ../myapp-hotfix

You now have two VS Code windows, each with a full editor experience, each on a different branch. No branch switching, no lost terminal sessions.

Running tests in parallel

Worktrees let you run the test suite in parallel across branches — useful when you need to compare test output between a feature branch and main:

# Terminal 1 — main branch tests
cd ~/projects/myapp
npm test 2>&1 | tee /tmp/test-main.txt

# Terminal 2 — feature branch tests (simultaneously)
cd ~/projects/myapp-feature
npm test 2>&1 | tee /tmp/test-feature.txt

# Diff the output
diff /tmp/test-main.txt /tmp/test-feature.txt

Cleaning up worktrees

# Remove a worktree (deletes the directory and deregisters the worktree)
git worktree remove ../myapp-hotfix

# Force remove if directory has changes
git worktree remove --force ../myapp-hotfix

# Prune stale worktree references (if you deleted the directory manually)
git worktree prune

Worktrees for code review

Instead of checking out a PR branch and losing your current state, create a worktree:

# Review PR #142 without losing your current branch
git fetch origin pull/142/head:pr-142
git worktree add ../myapp-pr-142 pr-142

# Review, test, leave comments
# Clean up
git worktree remove ../myapp-pr-142
git branch -d pr-142

One constraint to know about

A branch can only be checked out in one worktree at a time. If you try to add a worktree for a branch that is already checked out somewhere, git will refuse. This prevents conflicts, but it means you cannot open the same branch in two directories simultaneously.

The workaround: use separate branches that track the same remote. Or simply be aware that you need to move work to the existing worktree for that branch.

When worktrees change your workflow

The biggest change for me: I stopped using git stash almost entirely. Stashing has a subtle cost — you lose the mental context of what you were doing and why. With a worktree, the code is right there in a separate window, exactly as you left it, ready to pick up when the interruption is handled.

Three commands — worktree add, worktree list, worktree remove — and you will not miss stashing.