Git Worktrees: Work on Multiple Branches Simultaneously

The Problem Worktrees Solve

You're deep in a feature branch when a critical bug is reported on production. You stash your changes, switch branches, fix the bug, deploy, then switch back and pop the stash. If your project has a large build or node_modules, this context-switching costs 5-10 minutes every time.

Git worktrees let you check out multiple branches simultaneously in different directories — each with its own working tree, but sharing the same git history and objects.

Creating a Worktree

# You're on feature/dashboard working on a big feature
git branch
# * feature/dashboard
#   main

# Create a worktree for a hotfix WITHOUT touching your current work
git worktree add ../my-app-hotfix hotfix/critical-bug

# Or create a worktree for a new branch
git worktree add -b hotfix/login-bug ../my-app-hotfix main

# Now you can work in both directories simultaneously
cd ../my-app-hotfix   # hotfix branch
# ... make fixes, commit, push, deploy ...

cd ../my-app          # back to feature/dashboard — untouched!

Common Worktree Workflow

# List all active worktrees
git worktree list
# /Users/me/my-app          abc1234 [feature/dashboard]
# /Users/me/my-app-hotfix   def5678 [hotfix/critical-bug]

# After finishing the hotfix
cd ../my-app-hotfix
git commit -m "fix: resolve critical auth bug"
git push origin hotfix/critical-bug

# Remove the worktree
cd ../my-app
git worktree remove ../my-app-hotfix

# Or force-remove if it has uncommitted changes
git worktree remove --force ../my-app-hotfix

Worktrees for PR Reviews

Code reviews are much better when you can actually run the code:

# Checkout a PR for review in a separate directory
git fetch origin pull/142/head:pr-142
git worktree add ../pr-review-142 pr-142

cd ../pr-review-142
npm install  # install any new deps the PR added
npm run dev  # run the actual changes

# After review, clean up
cd ../my-app
git worktree remove ../pr-review-142
git branch -d pr-142

Worktrees for Release Management

# Keep a permanent worktree for your main branch
mkdir ~/worktrees
git worktree add ~/worktrees/main main
git worktree add ~/worktrees/staging staging

# Now you always have main and staging available without context switching
# Great for: checking if a bug is on main, comparing behavior, quick deploys

Important Limitations

• Each worktree needs its own node_modules if dependencies differ between branches
• You can't check out the same branch in two worktrees simultaneously
• Worktrees share the .git directory — be careful with git hooks that assume a single working directory

Worktrees + VS Code

Open each worktree as a separate VS Code window. Use VS Code workspaces to save multi-root configurations. Each VS Code window operates independently — separate terminals, extensions state, and editor state — making parallel work genuinely seamless.