Worktrees

Story

Building-a-house world — same site and crew as every Phase 0 lesson.

You already know the sample build trick from lesson 0.3: before touching the real house, the crew puts up a sample off to the side — same master plans, separate patch of land — tries the risky idea there, then merges it in or tears it down.

Now two crews want to work at once. Crew A is testing a new kitchen layout. Crew B is testing solar panels. But there's one cleared lot to build a sample on. So they fight over it: Crew A lays out the kitchen, Crew B shoves it aside to mock up the panels, the kitchen pieces get scattered, nobody knows whose half-built mess is whose. One lot, two crews = collisions.

The fix is obvious once you see it: clear a second lot. Crew A keeps the kitchen sample on lot 1. Crew B builds the solar sample on lot 2. Same master plans feed both. Neither crew bumps the other. Two samples rise at the same time.

That extra lot, cut from the same master plans, holding a different sample — that's a worktree.

The idea

A worktree is an extra working folder attached to the same repo, with its own branch checked out. One repo, several folders, each on a different branch — all sharing one history underneath.

First, the problem it solves. A normal repo folder is one lot: it can only show one branch at a time. The technical name for "the branch this folder is currently on" is HEAD — think of it as a you-are-here pin stuck in the build diary. A folder has exactly one HEAD pin. So if two sessions point at the same folder and switch to different branches, they yank that one pin back and forth, overwriting each other's files and stranding half-done work. One folder = one HEAD = one branch at a time. That's the collision.

Git's own words for the fix:

"Manage multiple working trees attached to the same repository."

The folder you first cloned into is the main worktree. Every extra one you add is a linked worktree:

"A repository has one main worktree (if it's not a bare repository) and zero or more linked worktrees. When you are done with a linked worktree, remove it with git worktree remove."

Three things to hold onto:

1. Each worktree is a real folder with its own HEAD. Lot 1 on feat/kitchen, lot 2 on feat/solar. Edit both at once — no stomping.
2. They share ONE history (one .git). Same master plans, same commits, same remotes. A worktree is not a second copy of the whole repo — far lighter than cloning again.
3. Git blocks the same branch in two worktrees. Built-in guard: "By default, add refuses to create a new worktree when <commit-ish> is a branch name and is already checked out by another worktree…" So you can't accidentally have two folders both editing feat/kitchen and diverging. One branch lives in exactly one lot.

When do you actually need one? (the decision)

This is the part that makes it click — don't reach for a worktree by reflex.

• One thing at a time → don't bother. Stay in your one folder and switch branches between tasks (git switch). Finish the kitchen, commit, then start solar. Sequential. Simplest.
• Two things in flight at the SAME wall-clock moment → use a worktree. Two terminal sessions, two AI agents, or "I need version A and version B both running so I can compare them side by side." That genuinely needs two folders.

One-look — same repo, two lots, two HEADs

        ┌─────────────────────────────┐
        │   ONE repo history (.git)   │   ← master plans, shared
        │     A──B──C  (all commits)  │
        └───────┬───────────┬─────────┘
                │           │
   ┌────────────▼──┐   ┌────▼───────────────┐
   │ MAIN worktree │   │  LINKED worktree   │
   │ gh-600-prep/  │   │ gh-600-prep-solar/ │
   │ HEAD → main   │   │ HEAD → feat/solar  │
   │ session 1     │   │ session 2          │
   └───────────────┘   └────────────────────┘
        no stomping — each lot has its own HEAD pin

Two folders, two HEAD pins, one shared history. Session 1 never touches session 2's files. Compare that to one folder, where both sessions would fight over a single HEAD pin.

Real example — the syntax teaser

Not heavily drilled on the exam, but you'll use this constantly the moment you run parallel work or parallel agents. Recognize the four commands.

# From inside your repo (the main worktree).

# 1. Add a NEW lot. Make a folder next door, check out a branch there.
git worktree add ../gh-600-prep-solar feat/solar
#                 └─ path of the new folder   └─ branch to check out there

# 1b. Add a lot AND create a brand-new branch in one shot (-b)
git worktree add -b feat/solar ../gh-600-prep-solar
#                   └─ new branch name   └─ new folder

# 2. List every worktree + which branch each is on
git worktree list
#  /Users/.../gh-600-prep         abc1234 [main]
#  /Users/.../gh-600-prep-solar   def5678 [feat/solar]

# 3. Work in the new folder independently. To view BOTH versions of the
#    site at once, run a second server there on a DIFFERENT port:
cd ../gh-600-prep-solar && python3 -m http.server 8766   # main one stays on 8765

# 4. Done (branch merged)? Remove the lot. History is untouched — only the
#    extra folder goes away.
git worktree remove ../gh-600-prep-solar

Map it to the story: add = clear a new lot and stand a sample on it · list = walk the site, see every lot and what's on it · the second server on port 8766 = a separate front door so you can tour both sample houses at once · remove = clear the lot away when the sample's been copied into the real house.

Why this matters for GH-600

This is the same isolation idea that lets multiple agents run in parallel without colliding — each agent gets its own worktree (or branch + sandbox), works in isolation, and proposes a PR. That's the backbone of multi-agent orchestration (Phase E): an orchestrator hands each sub-agent its own lot so a planner, a coder, and a reviewer never trample each other's files.

It also reinforces the Phase 0 spine: one branch = one unit of work, and main only ever receives finished, reviewed work. Worktrees just let you have several of those units physically open at once.

Check-in — three quick questions

Open-ended. Think first, then peek at the suggested answer.

1. In one sentence — what is a worktree, and what problem does it solve?

   Suggested answer

   A worktree is an extra folder attached to the same repo, with its own branch (its own HEAD) checked out, sharing one history underneath. It solves the "one folder = one branch at a time" collision so you can work on two branches truly in parallel.

2. You're running two Claude sessions in the same folder, each on a different branch. What goes wrong, and what's the fix?

   Suggested answer

   A folder has one HEAD — one checked-out branch at a time. Two sessions in the same folder yank that single HEAD back and forth, overwriting each other's working files and stranding uncommitted work. The fix: give each concurrent branch its own folder with git worktree add, one session per worktree.

3. How does the worktree idea connect to running multiple agents in parallel (Phase E)?

   Suggested answer

   Each agent gets its own worktree (or isolated branch/sandbox) so their file edits never collide — exactly like two crews on two lots. That isolation is what lets an orchestrator run a planner, coder, and reviewer in parallel safely. It's the foundation of multi-agent orchestration (Phase E).

Mentor marks this lesson verified after you compare answers and say "got it" in chat.