Gitastic
Path › Part 5: Power tools › Lesson 15 of 16
15

Worktrees: many desks, one repo

Work on two branches at the same time — without stashing or switching.

1 Learn the idea

You are halfway through a feature, files everywhere, nothing ready to commit. Then: "Production is down, can you fix it now?" Your options so far were git stash + git switch, or a quick messy commit. Worktrees give you a third, calmer option.

How it works

  • git worktree add ../hotfix -b hotfix main creates a new folder ../hotfix with a new branch hotfix checked out, starting from main.
  • Every worktree has its own working directory, staging area and HEAD — but they all share the same commits and branches.
  • A commit made in one worktree is instantly visible from the others (it is the same repository).
  • A branch can be checked out in only one worktree at a time — git refuses otherwise, so two desks never fight over the same branch.

2 Watch it happen

A hotfix without touching your half-done work

Press Play or use → to step through. Watch the graph as each command runs.

your laptop ~/project · on feature
e00120d Initial appe00120dInitial app5730c8d Start search feature5730c8dStart search f…Branch "main" — a movable pointermainHEAD = where you are. It points at the current branch.HEAD →Branch "feature" — a movable pointer (current branch: moves when you commit)feature
Worktrees (folders sharing one .git)
~/project
on feature
you are here
Working directoryyour folder / editor
app.js
search.jschanged
git add →← git restore
Staging areathe next snapshot (index)
app.js
search.js
git commit →← restore --staged
RepositoryHEAD → 5730c8d
app.js
search.js
terminal · simulated, no real repository is touched
Read this demo as text
  1. $ git status

    We are on feature with uncommitted changes in search.js. Then the call comes: production is crashing!

  2. $ git worktree add -b hotfix ../hotfix main

    One command: a new folder ~/hotfix, a new branch hotfix starting at main, checked out there. Notice the worktree: hotfix label in the graph.

  3. $ cd ../hotfix

    We walk to the second desk. It is clean and on hotfix. Our unfinished search.js work is still sitting safely on the first desk.

  4. $ edit app.js "app without crash bug"
$ git commit -am "Fix crash in production"

    Fix and commit, as usual. The commit lands in the shared repository — the graph shows it on hotfix.

  5. $ git worktree list

    git worktree list shows every desk, which commit it is on, and which branch.

  6. $ cd ~/project

    Back to the first desk…

  7. $ git status

    …and our half-done work is exactly as we left it. No stash, no WIP commit, no lost focus.

  8. $ git switch hotfix

    Trying to check out hotfix here too? Git refuses: that branch is already in use by the ~/hotfix worktree. One branch, one desk.

  9. $ git worktree remove ../hotfix

    Done with the hotfix? Remove the worktree. The folder disappears, but the branch and its commit stay — you can still merge or push hotfix.

  10. $ git branch

    hotfix is still listed. Worktrees are just desks; the work lives in the repository.

stash + switch
  • One folder, one branch at a time
  • Must pack up your changes first
  • Easy to forget what is in the stash
worktree
  • One folder per branch, side by side
  • Your changes never move
  • Costs almost no disk space: history is shared
git worktree add -b <new> <path> [<start>]New folder with a new branch checked out
git worktree add <path> <branch>New folder for an existing branch
git worktree listShow all worktrees and their branches
git worktree remove <path>Delete the folder (the branch stays)

3 Check your understanding

Question 1

What do all worktrees of one repository share?

Question 2

This repo has a worktree at ~/review. You are in ~/project and run git switch pr-42. What happens?

your laptop ~/project · on main
e00120d Initial appe00120dInitial app8a29d05 My feature work8a29d05My feature workBranch "pr-42" — a movable pointerpr-42Another worktree has this commit checked outworktree: reviewHEAD = where you are. It points at the current branch.HEAD →Branch "main" — a movable pointer (current branch: moves when you commit)main
Worktrees (folders sharing one .git)
~/project
on main
you are here
~/review
on pr-42
Question 3

You run git worktree remove ../hotfix. What happens to the hotfix branch and its commits?

Question 4

Which situation is the best fit for a worktree?

0/4 answered

4 Practice for real

Your mission

Fix production without packing up

You are mid-way through dark mode on feature, with an uncommitted theme.css. Without committing or stashing that work: create a worktree at ../hotfix on a new branch hotfix starting from main, commit a fix there, then return to ~/project.

your laptop ~/project · on feature
e00120d Initial app click to insert the hash into the terminale00120dInitial app5fe1015 Start dark mode click to insert the hash into the terminal5fe1015Start dark modeBranch "main" — a movable pointermainHEAD = where you are. It points at the current branch.HEAD →Branch "feature" — a movable pointer (current branch: moves when you commit)feature
Worktrees (folders sharing one .git)
~/project
on feature
you are here
Working directoryyour folder / editor
app.js
dark.js
theme.cssnew
git add →← git restore
Staging areathe next snapshot (index)
app.js
dark.js
git commit →← restore --staged
RepositoryHEAD → 5fe1015
app.js
dark.js
terminal · simulated, no real repository is touched
Type commands below. `help` lists everything. Tab completes, ↑ recalls. Click a commit to paste its hash.
~/project (feature) $