worktree: Parallel Checkouts

worktree — multiple checkouts, one repo

The classic interruption story: you are mid-feature on feature/x, an urgent bug needs a fix on main, and you cannot stash because the in-progress code does not yet build. The old answer was a second clone of the repo. The modern answer is git worktree: a single .git/ shared across multiple checked-out copies of different branches. Same commits, same hooks, same config — different working trees, side by side.

git worktree add ../repo-hotfix hotfix/login creates a new worktree at ../repo-hotfix with hotfix/login checked out. The original worktree at ./repo still has feature/x. You switch projects by changing directories, not branches. The shared .git/ means commits made in either worktree are visible from the other immediately. git worktree list shows all checkouts; git worktree remove ../repo-hotfix retires one when the work is done.

Three high-leverage use cases. Hotfix during in-progress work — branch the hotfix into a worktree, fix and ship, return to the feature without ever stashing. Long-running comparison or build — run a long test against one worktree on an old commit while you keep working on the new commit in the original. Reviewing a teammate's PR — git worktree add ../repo-pr-142 pr/142 gives you their branch checked out cleanly without disturbing your main branch checkout.

Two gotchas. The same branch cannot be checked out in two worktrees at once — Git refuses. (Use git worktree add --detach if you really want a read-only view.) Worktrees consume disk: each is a full working-tree copy, just without its own .git/objects/. For huge repos, partial-clone or sparse-checkout in the secondary worktree saves significant space. The CI integration is also nice — Vercel and similar platforms can deploy each worktree independently.

Code

Common worktree workflows·bash

# Add a new worktree on a different branch:
git worktree add ../repo-hotfix hotfix/login

# Add a worktree from a specific commit (detached HEAD):
git worktree add --detach ../repo-snapshot v1.4.0

# Add a worktree and create a new branch in one step:
git worktree add -b feature/profile ../repo-profile main

# List all worktrees of this repo:
git worktree list

# Retire a worktree when done:
git worktree remove ../repo-hotfix

# If a worktree directory was deleted manually, prune the registry:
git worktree prune

Reviewing a PR via worktree·bash

# Use gh to fetch the PR's branch + create worktree:
gh pr checkout 142
# That switches your current worktree. Better:

git fetch origin pull/142/head:pr/142
git worktree add ../repo-pr-142 pr/142
cd ../repo-pr-142
npm install
npm run dev          # run their version of the app
# When done reviewing:
cd ../repo
git worktree remove ../repo-pr-142
git branch -D pr/142

Exercise

On any active project, create a second worktree with git worktree add ../repo-side hotfix-test. Run git worktree list and confirm both. Make a commit in the new worktree, switch to the original directory, and verify the commit shows up in git log from there. Remove the worktree with git worktree remove. Note in writing one workflow you currently use stash for that worktree would handle better.

worktree: Parallel Checkouts

worktree — multiple checkouts, one repo

Code

External links

Exercise

Progress

Comments 0