git worktree — Multiple Working Trees

Normally, a Git repository has one working directory tied to one branch. git worktree lets you have multiple working directories, each checked out to a different branch — all sharing the same .git data.

The Problem

You are deep in a feature branch when someone asks you to review a pull request on another branch. Your options:

1. Stash and switch — git stash, git checkout pr-branch, review, switch back, git stash pop
2. Clone again — make a second clone of the whole repo
3. Use worktree — create a linked working tree on the other branch

Option 1 is error-prone (stash conflicts, forgetting to pop). Option 2 wastes disk space and time. Option 3 is clean and fast.

Creating a Worktree

# Create a new working tree for an existing branch
git worktree add ../project-review pr-branch

# Create a new working tree with a new branch
git worktree add ../project-experiment -b experiment

This creates a new directory with the checked-out branch. The new directory shares the same Git history — no extra cloning, no extra disk space for objects.

Managing Worktrees

# List all worktrees
git worktree list

# Output:
# /home/user/project          abc1234 [main]
# /home/user/project-review   def5678 [pr-branch]

# Remove a worktree when done
git worktree remove ../project-review

# Or just delete the directory and prune
rm -rf ../project-review
git worktree prune

Use Cases

Reviewing PRs While Working

# You're working on feature-x
# Someone opens a PR from fix/login

git worktree add ../review-login fix/login
cd ../review-login
# Run tests, review code
# When done:
cd ../project
git worktree remove ../review-login

Running Tests on Another Branch

# Run tests on main without leaving your feature branch
git worktree add ../test-main main
cd ../test-main
npm test
cd ../project
git worktree remove ../test-main

Comparing Behavior Across Branches

With two worktrees, you can run both versions of your app simultaneously on different ports and compare behavior side by side.

Worktree vs Stash-Based Workflow

Rules and Limitations

• Each branch can only be checked out in one worktree at a time
• Worktrees share the same .git directory, so operations like git stash affect all worktrees
• Deleting a worktree directory without git worktree remove leaves a stale entry (clean up with git worktree prune)

Key Points

• git worktree add <path> <branch> creates a new working tree for a branch
• git worktree list shows all active worktrees
• git worktree remove <path> cleans up a worktree
• Worktrees are ideal for reviewing PRs, running tests, or comparing branches without disrupting your current work