When to create a git worktree

Every guide about worktrees explains how to make one. Almost none says when, so the tool gets used as a reflex — and the cost lands later, as four half-set-up checkouts holding branches you can't delete and can't remember.

This skill is only the decision. Make it before you type git worktree add.

The one-line test

Do two working states of this repo need to be live at the same time?

Live at the same time — not "both exist", not "both matter this week". If one can finish, or even just pause cleanly, before the other starts, you want git switch, not a worktree.

What a worktree actually buys

A second working tree over the same object store and the same branch namespace. That single sentence contains everything that makes the decision:

The right column is where worktrees go wrong. Not knowing it is how people create one to run tests in parallel and then discover both runs are fighting over the same dev database.

Decide in four questions

Run them in order and stop at the first that answers.

1. Is anything running or warm in the current tree? A reproduction you finally got, a debugger attached, a 6-minute build cache, a test suite mid-run, a long git bisect. git switch throws that away and git stash hides it somewhere repo-global you will forget. → Worktree.

2. Will two lines of work be edited concurrently — by two people, two agents, or you and a long job? → Worktree. See the always-case below.

3. Do I need both states visible at once? Diffing a regression against the last good tag, porting a fix between major versions, running old and new side by side to compare output. Nothing sequential gives you this. → Worktree.

4. Otherwise → no worktree. Switch the branch. Sequential work on a clean tree is what branches are for, and the checkout you already have is set up.

The always-case: concurrent agent sessions

Two agents editing one checkout is not a slowdown, it is a correctness failure. They overwrite each other's edits with no conflict marker — git never sees it, because it never reached the index. Worse, each agent's test run observes the other's half-written files, so both results are noise: a green run proves nothing and a red run points at the wrong cause.

So: concurrent sessions always get a fresh branch and a fresh worktree, never shared main. This is the one case where you skip the cost/benefit entirely — the shared-tree option isn't slower, it's invalid.

Corollary for a single agent: if you are about to spawn parallel work on one repo, decide the worktree layout before launching, not after the first collision.

The blocker check (do this before worktree add)

A worktree duplicates files. It does not duplicate the world those files talk to. Before creating one, name every singleton the work touches:

• a fixed port in a committed config
• a dev database or a shared schema/migration state
• a named container, volume, or docker compose project
• a daemon / watcher / language server bound to one absolute path
• an .env with a token that only one session may hold at a time
• a lockfile outside the repo (global package cache, license daemon)

If any exist, the worktree gives you two checkouts racing over one resource, and the failures look like flaky tests rather than like what they are. Two honest ways out:

• Parameterize the singleton (per-worktree port, per-worktree DB name / compose project) — this is the real setup cost of worktrees, and it is worth paying once per repo if you will do this often; or
• Don't use a worktree. Sequence the work instead. A worktree whose external state collides is worse than the branch switch it replaced.

Deciding "I'll sort it out when it breaks" is choosing the flaky-test outcome.

Don't create one when

• The change is trivial and the tree is clean — just switch.
• You're already on the right branch in the current tree.
• The work is short and setup is long (a large install, migrations, a codegen step). Setup cost is per-worktree; if setup exceeds the task, the worktree is the task.
• You only want to look at another branch: git show, git diff, git log -p, or git restore --source read other commits without a second tree.
• The repo has heavy submodules — they are not shared and must be re-initialized per worktree. Weigh that before, not after.

Teardown is part of the decision

Creating a worktree commits you to removing it. An abandoned one keeps its branch checked out, which silently blocks git branch -d, keeps stale build output on disk, and makes git worktree list useless as a picture of what's in flight.

So decide up front, in one sentence: what event ends this worktree? ("Merged", "spike answered", "the agent run finishes.") If you can't name the end, you're not making a worktree — you're making a second permanent checkout, and should say so deliberately.

Then actually do it:

git worktree list                 # what exists, and is any of it finished?
git worktree remove <path>        # removes the tree; refuses if dirty
git worktree prune                # clears records of trees deleted by hand

Sweep at the natural boundary — end of session, or right after a merge. Not "later".

Decision record

Mechanics are deliberately out of scope

Once the decision is yes, the setup problems — copying .env, linking or installing dependencies, assigning a deterministic port per worktree, sweeping stale trees — are solved work with existing tools. Crib from prior art rather than reinventing; keep this skill about the choice.