Practice: Worktrees and parallel agents

Self-check questions

Answer each in your own words first, then open the answer to check.

Q1. What is a git worktree, in your own words? How does it differ from a clone?

Show answer

A separate working directory attached to the same git repository. Multiple folders share one .git/ (the database of commits, branches, tags). Each folder has its own branch checked out and its own uncommitted working state. Differs from a clone in that the git history is SHARED (no duplication, no push/pull between worktrees) rather than independently copied.

Q2. Why does git refuse to let you check out the same branch in two worktrees?

Show answer

Because two working trees both trying to commit to the same branch is asking for race conditions and chaos. Git’s design assumes one branch = one current “working state” at a time. If you genuinely need to inspect the same commit in two places, use detached HEAD in one of them (git worktree add --detach <path> <sha>).

Q3. Name two situations where a worktree is clearly better than checkout-switching.

Show answer

Frequent context-switching (multiple times per hour): worktrees eliminate the stash/checkout/unstash ceremony.
Long-running operations on one branch (a 45-minute test) while you continue work on another: checkout-switching would block you; worktrees let both happen.

Q4. Name one situation where multiple clones are better than worktrees.

Show answer

Working across multiple machines. Worktrees can’t share a database across machines; clones can sync via a shared remote. So if you want to work on the same repo from your laptop and your desktop, separate clones (with push/pull) are the answer.

Q5. What does git worktree prune do?

Show answer

Cleans up internal records of worktrees whose folders have been manually deleted (e.g. you rm -rf a worktree folder without first running git worktree remove). After pruning, git worktree list shows only the worktrees whose folders actually exist.

Q6. What happens to commits made in a worktree: are they visible from other worktrees of the same repo?

Show answer

Yes, via the shared .git/. A commit you make in worktree A is immediately part of the database all other worktrees of the same repo share. Running git log --all in any worktree shows commits made in any other worktree (across all branches).

The only caveat: a commit is visible on its BRANCH. If worktree A made a commit on branch feature-A, that commit is visible in worktree B if B looks at feature-A (or runs git log --all), but it’s NOT in worktree B’s CURRENT branch unless B merges or cherry-picks.

Q7. Why are worktrees a particularly good fit for parallel AI agent workflows?

Show answer

Each agent gets its own working directory (no file-edit interference between agents).
Each agent gets its own branch (no commit-history collision).
All agents share the same .git/ (their commits are immediately visible to the lead and to each other).
Worktrees are cheap to create and destroy (one command each), matching the “spin up 6 agents for an hour, tear down” lifecycle.

The alternative, multiple clones, would mean more disk space, push/pull ceremony between clones, and slower fleet setup/teardown. Worktrees are simply the right shape for this work.

Q8. What’s the disk-space tradeoff of using worktrees vs single-checkout?

Show answer

A single-checkout uses 1x git database + 1x working tree. A clone uses 2x git database + 2x working tree. A worktree-pair uses 1x git database + 2x working tree.

So worktrees save the git-database duplication (which for a large repo can be hundreds of megabytes) but still use one full working tree per attached folder. Lighter than clones, heavier than single-checkout.

Worktree basics drill

In any git repo (or create a fresh one), confirm your current branch with git branch.
Run git worktree add ../wt-test main (or any other branch you have).
cd ../wt-test and confirm you’re on the chosen branch.
cd back to your original repo. Confirm your original branch is still checked out.
Run git worktree list. You should see both worktrees.
Make a commit in your original repo (modify a file, add, commit).
Run git log --oneline in ../wt-test. The new commit should NOT appear (it’s on a different branch).
Run git log --all --oneline in ../wt-test. The new commit SHOULD appear (it’s reachable via the other branch).
cd to original repo. Run git worktree remove ../wt-test.
Verify the folder is gone.

Worktree-with-new-branch drill

From your main repo, run git worktree add -b feature/experiment ../wt-experiment main.
cd ../wt-experiment and confirm a new branch feature/experiment is checked out.
Make a couple of commits.
cd back to main repo. Run git branch. You should see feature/experiment listed.
Try git checkout feature/experiment in the main repo. It should FAIL (because the branch is checked out in the worktree).
Remove the worktree (with --force if you have uncommitted work you want to discard, or commit/push first).
After removal, you should be able to check out feature/experiment in the main repo.

Multi-worktree drill (the agent simulation)

From your main repo, create 3 worktrees with new branches:

git worktree add -b sim-agent-1/feature-a ../sim-1 main
git worktree add -b sim-agent-2/feature-b ../sim-2 main
git worktree add -b sim-agent-3/feature-c ../sim-3 main

In each worktree (open 3 terminal tabs), make a few commits with distinct file changes.
Back in the main repo, run git log --all --oneline --graph.
You should see all three branches’ commits in the unified graph.
Pick one of the agent branches and merge it into a new branch integration:

git checkout -b integration main
git merge sim-agent-1/feature-a

Repeat for the other two (or cherry-pick specific commits from them).
After integration, clean up:

git worktree remove ../sim-1
git worktree remove ../sim-2
git worktree remove ../sim-3
git branch -D sim-agent-1/feature-a sim-agent-2/feature-b sim-agent-3/feature-c

Worktree-vs-clone comparison drill

Take any existing repo. Note its disk size (du -sh .).
Create a fresh clone of the same repo nearby. Note the clone’s disk size.
Now create a worktree of the original on a different branch. Note the new worktree’s size.
Compare: the clone has its OWN .git/, the worktree does not. The clone uses ~2x disk; the worktree uses ~1x (database) + 1x (working tree).

This drill is just to make the disk-space difference real.

Scenario reflections

Scenario A: Your project’s full integration test suite takes 60 minutes. You want to run it on your current branch while continuing to write code on the same project. Walk through how you’d use worktrees.

Show answer

git worktree add ../test-current HEAD
cd ../test-current
./run-test-suite.sh > test-output.log 2>&1 &       # background
cd ~/projects/myrepo                                # back to main work, continue coding

When the test finishes (60 min later), cd ../test-current and check test-output.log. After confirming, git worktree remove ../test-current.

The trick is HEAD as the branch: same branch as your current work, but in a separate folder. The constraint “same branch in two worktrees is forbidden” is the problem. Workaround: use --detach to start the test worktree in detached-HEAD mode at the same commit:

git worktree add --detach ../test-current HEAD

Now both folders are at the same commit, but only your main folder is on the branch. Tests run on the detached state; coding continues on the branch.

Scenario B: You’re a maintainer on an open-source project. You typically review 5-10 PRs per week, often needing to actually run the contributor’s code (not just read the diff). Walk through your worktree workflow.

Show answer

# For each PR
git fetch origin pull/<PR-number>/head:pr-<PR-number>
git worktree add ../pr-<PR-number> pr-<PR-number>
cd ../pr-<PR-number>
# review: run the code, test, comment on the PR via UI
cd ~/projects/myrepo
git worktree remove ../pr-<PR-number>
git branch -D pr-<PR-number>

For high-volume maintainers, often a small shell function or script encapsulates this. The friction drops from minutes to seconds per PR review.

Scenario C: You’re starting an AI-agent workflow where 6 agents will work in parallel on different parts of a feature. The agents take 30-45 minutes each. Walk through your fleet setup and teardown.

Show answer

cd ~/projects/myrepo
git checkout main && git pull

for i in 1 2 3 4 5 6; do
    git worktree add -b agent-$i/feature ../agent-$i main
done

# Launch 6 agent sessions, each pointing at ../agent-N
# Watch progress from main repo:
git log --all --oneline --graph

# When agents finish (some sooner than others), integrate:
git checkout -b integration main
git merge agent-1/feature        # or cherry-pick specific commits
# ... and so on for each ...

# Teardown:
for i in 1 2 3 4 5 6; do
    git worktree remove ../agent-$i
    git branch -D agent-$i/feature
done

The fleet existed for the duration of the agent work (an hour or two), then disappeared.

Scenario D: You created a worktree last week for a project you’ve since dropped. You don’t remember the folder. How do you find it and clean up?

Show answer

git worktree list
# /Users/you/myrepo                    abc1234 [main]
# /Users/you/wt-forgotten-experiment   def5678 [feature/old-experiment]

The list reveals where it lives. cd /Users/you/wt-forgotten-experiment to inspect. If you don’t care:

git worktree remove --force /Users/you/wt-forgotten-experiment
git branch -D feature/old-experiment       # if you don't want the branch either

If the folder was manually deleted (just rm -rf-ed), the list will still show it, but pointing at a nonexistent path. Then:

git worktree prune     # cleans up the record

Flashcards

Q. What is a worktree

A separate working directory attached to the same git repository: multiple folders sharing one .git/, each on its own branch

Q. Create a worktree

git worktree add <path> <branch>

Q. Create with a new branch

git worktree add -b <newbranch> <path> <baseref>

Q. List worktrees

git worktree list

Q. Remove a worktree

git worktree remove <path> (add --force if uncommitted changes you want to discard)

Q. Prune stale records

git worktree prune (cleans up records for folders you deleted manually)

Q. Constraint: one branch per worktree

Cannot have the same branch checked out in two worktrees; git rejects

Q. Worktree vs clone

Worktree shares git history (one .git/), clone duplicates it. Worktree commits are instantly visible across worktrees; clone needs push/pull.

Q. When to prefer clone

Truly independent copies, working across machines, want isolation from teammates’ pushes

Q. When to prefer worktree

Parallel branches same machine, save disk space, multi-agent workflows, frequent context-switching

Q. Multi-agent fleet pattern

One worktree per agent, each on its own branch; commits flow into shared .git/; lead integrates

Q. Long-running test pattern

Worktree on the branch being tested; run test there; main worktree continues with other work

Q. Hotfix during feature pattern

Worktree on hotfix branch off main; fix in the new worktree; remove when shipped; original feature work undisturbed

Q. Common confusion

Forgetting which folder you’re in: fix via terminal prompt and naming convention

Q. Common mistake

Forgetting to clean up old worktrees: run git worktree list periodically