using-worktreeslisted

# Using Worktrees ## Overview **Core principle:** A git **worktree** is a second working directory backed by the *same* repository, checked out to its own branch. Two worktrees are two real folders that share history but have completely separate files — so two agents can edit at once without stepping on each other, and a risky experiment lives somewhere you can delete without touching your main checkout. This is the isolation that makes **parallel *writing*** safe. Parallel *reading* never needs it — see **dispatching-subagents**. ## When to Reach for One - **Concurrent edits.** Two or more agents that will *write* files in parallel. Without isolation they race and corrupt each other's changes. - **Throwaway experiments.** A spike you want to run for real but keep off your main branch. - **Keeping main clean.** Work in progress stays on its own branch in its own directory; your primary checkout is untouched. **Not worth it for:** read-only fan-out, or a single sequential edit. Worktrees cost disk and setup — spend them only when writes actually collide. (Same host-budget instinct as everywhere else.) ## Step 0 — Are You Already Isolated? **Before creating anything, check whether you're already in a worktree.** Harness-created isolation fools the eye — don't stack a second worktree on top of one. ```bash # In a linked worktree, the git-dir and the common git-dir differ [ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ] && echo "linked worktree" ||