Worktrees: Multiple Branches Checked Out at Once

In one line

git worktree lets you check out more than one branch simultaneously, each in its own separate folder, sharing the exact same underlying repository — no stashing, no switching back and forth.

0/5 · 0%

Think of it like this

Instead of constantly clearing your desk to switch between two different projects (stashing, switching branches, switching back), having two separate desks — one already set up for each project — that you can walk between instantly, with nothing to pack away or restore each time.

Key ideas

01
Normally, a single Git repository has exactly ONE working directory, and switching branches (git switch) changes what that one directory contains — this is exactly why uncommitted changes need to be stashed or committed before switching, since only one branch's content can occupy that directory at a time.
02
git worktree add <path> <branch> creates a SECOND (or third, or more) working directory, at a new path, with a DIFFERENT branch checked out — both working directories share the exact same underlying repository (the same .git data, same commits, same remotes), but each has its own independent set of files on disk that you can edit simultaneously without any conflict between them.
03
This directly solves the 'urgent interruption while mid-feature' problem from Topic 6.1 in a genuinely different way than stashing: instead of shelving your in-progress feature work to switch branches in the SAME directory, you simply cd into a separate worktree that already has main (or whatever branch you need) checked out — your feature work in the original directory is completely undisturbed, no stash needed at all.
04
git worktree list shows every worktree currently associated with the repository and which branch each one has checked out. git worktree remove <path> cleans one up once you're done with it — importantly, you generally can't have the SAME branch checked out in two worktrees simultaneously, since Git enforces that each branch is checked out in at most one place at a time.
05
Worktrees genuinely shine for specific, recurring situations: running a long test suite or build against one branch while continuing to actively develop on another, reviewing a colleague's pull request in its own dedicated folder without disturbing your own in-progress work, or maintaining a permanently-checked-out main alongside your active feature branch for quick reference.

Code & diagrams

Worktreesdiagram

One repository, two independent working directories, two branches checked out at once.

Rendering diagram…

worktrees.shmarkdown

Two branches, checked out simultaneously, in two separate folders.

cd ~/scratch/my-first-repo

# You're mid-feature here, with uncommitted changes
git status
# feature.txt modified, not yet committed

# Instead of stashing to check something on main, add a second worktree
git worktree add ../my-first-repo-main main

# See both worktrees
git worktree list
# ~/scratch/my-first-repo       <branch: feature/my-branch>
# ~/scratch/my-first-repo-main  <branch: main>

# Work in the NEW worktree without touching your original one at all
cd ../my-first-repo-main
# main is checked out here — completely separate files on disk
ls
# your original directory's uncommitted feature.txt changes are untouched

# Back in your original directory, nothing was disturbed
cd ../my-first-repo
git status
# feature.txt is still modified, exactly as you left it — no stash was needed

# Clean up when you're done with the extra worktree
cd ..
git worktree remove my-first-repo-main

Explain it without notes

How is using a worktree genuinely different from just stashing and switching branches in the same directory?

Why can't the same branch be checked out in two different worktrees at the same time?

Practice

Create a second worktree for a different branch in a test repository, confirm with git worktree list that both are tracked, and edit a file in each independently to confirm they don't interfere with each other.

Attempt to check out the SAME branch in two different worktrees at once and read the exact error Git gives you.

Trade-offs

↔
Worktrees genuinely eliminate the small friction of stashing for short interruptions, but they do consume real disk space for each additional checked-out copy of the working directory (build artifacts, dependency folders, etc. often need to be reinstalled or rebuilt separately per worktree) — for very occasional, short interruptions, a quick stash is often simpler; for genuinely recurring parallel-work situations (regularly reviewing PRs, regularly needing a reference copy of main), the disk cost is easily worth the convenience.

Done when you can

I understand how a worktree differs from simply switching branches in the same directory.
I can create, list, and remove a worktree.
I know why the same branch can't be checked out in two worktrees simultaneously.