Workflow
/worktreeGit worktrees isolate local state, not design.
Two minds, one desk
Two tasks need separate working directories
You are midway through a feature when production needs a hotfix. In one folder, the usual options are to finish prematurely, commit unfinished work, stash it or switch branches while carrying local state. Each option adds a memory burden at the moment attention should be on the incident.
A Git worktree is another checked-out directory connected to the same repository. It has its own branch, files and uncommitted changes while sharing Git's underlying history and objects. The feature can remain in one directory and the hotfix can proceed in another. Isolation is real at the working-copy level, not universal across everything the tasks may touch.
Separate rooms, shared building
Two worktrees keep local files apart, but both still connect to common repository and service boundaries.
Worktree A
- Authentication update Own branch, files and uncommitted state
- Focused tests Runs against its local working copy
- New session interface A contract the other branch may depend on
shared contract
Worktree B
- Account settings update Own branch, files and uncommitted state
- Focused tests Can pass against the old interface
- Integration dependency Must adapt before the combined result is valid
No working-copy overwrite occurred. The integration test still has work to do.
The real culprit
A branch separates history; a worktree separates local state
A branch records a line of commits. It does not by itself give two simultaneous tasks separate files on disk. A worktree adds that physical separation. Each task can keep its own unfinished changes, generated files and test state without a stash becoming the only map back.
The analogy to clearing context is useful: unrelated work benefits from a clean working set. But a worktree is not a sandbox. Processes can still reach the same database, port, cache, credentials or cloud environment. Those shared resources need their own names, permissions and isolation.
A worked parallel example
Separate the edits, then reconcile the design
Suppose one agent updates an authentication library while another rewrites account settings. Give each a worktree and explicit file ownership. They can edit and test without overwriting the other's uncommitted files. The first agent changes the session interface, however, and the second still depends on the old one. Both branches pass their focused checks.
The collision has moved to integration. Git may expose a textual conflict, but this interface change can merge cleanly and still fail semantically. The integration test or reviewer must expose it. The integration owner chooses the new session interface, updates the settings branch to that contract and runs the combined authentication and account-settings checks. Only when those checks pass is the pair ready to merge. That is progress, not magic. Worktrees protect working copies; they do not make two designs compatible. Effective parallel work also needs bounded scope, agreed interfaces, integration tests and one owner for the merge.
The lopsided trade
Isolation has a cost; compare it with the collision risk
Worktrees are usually lightweight because Git shares repository objects, but they are not free. Dependencies, build output and local databases may be duplicated. Teams need naming, cleanup and a way to avoid two worktrees using the same port or migration target. For a tiny sequential edit, that ceremony may not pay.
Use a worktree when tasks must remain active at the same time, when local changes are costly to disturb or when several agents need clear filesystem ownership. The figure below is conceptual. The sensible comparison is the known setup and integration cost against the consequence and likelihood of a shared-workspace collision.
Choose isolation by expected cost
A worktree pays when the setup and integration burden is smaller than the likelihood and consequence of shared-state collisions.
Isolation cost
- Setup and naming Branch, directory and ownership conventions
- Duplicated local state Dependencies, build output and databases may multiply
- Resource separation Ports, migrations and credentials need deliberate handling
- Integration and cleanup Useful commits and lessons must be retained
compare, do not assume
Collision exposure
- Likelihood Will active tasks disturb the same working state?
- Consequence How costly would lost, mixed or unreconstructable work be?
- Duration How long must the tasks remain active together?
- Reversibility Can the shared edit be restored cheaply?
Tiny sequential edits may not earn isolation. Concurrent consequential work often does.
The practical rule
Isolate state, then plan the merge
Before parallel work begins, name five things: the branch and directory, files or components owned, shared resources that still need isolation, the interface both tasks may rely on and the person responsible for integration. Remove the worktree only after its useful commits and lessons are safely retained.
This is one layer of harness engineering: make safe working conditions the default. The student lesson is that separation moves some conflicts to a better boundary; it does not abolish them. The professional benefit is inspectability. Each task keeps a coherent working copy, and integration becomes an explicit decision rather than an accidental overwrite.