| name | using-git-worktrees |
| description | Use when work needs its own isolated checkout — parallel strands that would fight over files, or a risky change you want quarantined from the main tree. Gives each strand a real working directory on its own branch without re-cloning. |
| slipstream | {"category":"context","requires":[],"tags":["git","isolation","parallel"]} |
Overview
A single working tree can only hold one state at a time, so two strands of work editing the same files collide, and a risky experiment contaminates the tree you trust. A git worktree gives a branch its own directory backed by the same repository: separate files, shared history, no second clone. It is the isolation layer that makes [[dispatching-parallel-agents]] safe when strands would otherwise overlap.
Steps
- Decide isolation is warranted. Use a worktree when strands would edit the same files, or when a change is risky enough that you want it quarantined from the main tree. For disjoint files, plain parallel work is simpler.
- Create the worktree on a fresh branch:
git worktree add ../<name> -b <branch>. It is a full directory you can build and test in independently.
- Do the strand's work there in full — edit, build, run its verification — without touching the main tree.
- Integrate by merging or opening a pull request from the branch once its checks are green, exactly as you would any branch.
- Remove the worktree when done:
git worktree remove ../<name>. Do not leave stale worktrees; they drift and confuse later sessions.
Verify
Each isolated strand built and verified inside its own worktree, the main tree was never a shared edit surface, and every worktree was removed after its branch integrated.
