git worktree for Parallel Branches

You’re mid-feature, files half-edited, and a “can you review my PR?” or “prod is down” lands. The usual dance is git stash, switch branches, deal with it, switch back, git stash pop, and hope nothing got tangled. git worktree deletes that dance entirely: it checks out a second branch into its own folder, sharing the same underlying repo, so your half-done work just sits there untouched while you work somewhere else.

The problem with one working directory

A normal clone has exactly one working directory, so it can only have one branch checked out at a time. Switching branches with dirty files forces you to either commit prematurely or stash. Stashing works, but it’s a context-juggle — and stash pop after a branch switch is a classic source of “wait, where did my changes go?”

git worktree sidesteps the whole premise: one repo, many working directories, a different branch in each.

Creating a worktree

From inside your repo, check out a branch into a sibling folder:

git worktree add ../project-hotfix hotfix/payment-bug

That creates the directory ../project-hotfix with hotfix/payment-bug checked out. Your original folder keeps your feature branch and all its uncommitted changes, exactly as you left them. cd ../project-hotfix, fix the bug, commit, push — then come back and your feature work is right where it was.

What this does: the new folder is a full working directory, but it shares the single .git object store of the original repo — so there’s no re-clone, no duplicated history, no extra download. It’s the same repo viewed from two places at once.

To create a new branch in the worktree in one step:

git worktree add -b feat/experiment ../project-experiment main

-b feat/experiment creates the branch (off main) and checks it out into ../project-experiment together.

The everyday uses

• Review a PR without disturbing your work. git worktree add ../review pr-branch, run it, read it, delete the worktree — your feature branch never moved.
• Hotfix prod mid-feature. Spin a worktree on main, patch, ship, return. No stash, no premature commit of half-done work.
• Run two branches side by side. Compare behavior of main and your branch with both servers running at once — impossible in a single checkout.
• Long builds in the background. Let one worktree compile while you keep coding in another.

Managing worktrees

List them:

git worktree list

/home/jerwin/project           a1b2c3d [feat/passkey-login]
/home/jerwin/project-hotfix    e0f1a2b [hotfix/payment-bug]

When you’re done, remove a worktree cleanly:

git worktree remove ../project-hotfix

If you deleted the folder by hand and Git still lists a stale entry, prune the bookkeeping:

git worktree prune

The one rule: a branch lives in one worktree

Git won’t let you check out the same branch in two worktrees at once — try it and you get fatal: 'feat/x' is already checked out at '/path/...'. That’s a feature, not a limitation: it stops two folders from fighting over one branch’s state. Each worktree owns its branch; if you need the same branch in two places, you genuinely want two branches.

Caveats and best practices

• Keep worktrees outside the main folder. Put them in sibling directories (../project-hotfix), not nested inside the repo, or you’ll confuse your tooling and your .gitignore.
• Worktrees share branches and stashes but not the index. Uncommitted changes are local to each worktree’s directory — which is the whole point, but worth remembering.
• Clean them up. git worktree remove when done; stale worktrees accumulate and a forgotten one holding a branch can block operations on it later.
• Great with interactive rebase. Rebase a branch in one worktree while another stays on a known-good checkout — a safety net if the rebase goes sideways.

Conclusion

git worktree add ../project-hotfix hotfix/bug   # branch in its own folder
git worktree list                               # see them all
git worktree remove ../project-hotfix           # clean up when done

git worktree trades the stash-and-switch shuffle for a second folder, and once it’s in your toolkit the “I’m in the middle of something” excuse for not reviewing a PR or shipping a hotfix just disappears. One repo, many branches open at once — exactly as your actual work tends to be.