Git Worktree
An additional working directory attached to one repository, each on its own branch.
A git worktree is a second (or tenth) working directory backed by the same repository, each checked out to a different branch. It removes the need to stash and switch: several branches can be open, built, and running at once.
It is the standard answer to parallel work, and especially to several agents or processes working simultaneously — each gets a real directory that nobody else writes to. See Multi-Agent Orchestration.
The complications are all about the things a worktree does not isolate.
Untracked files do not come along. Environment files, local configuration, and installed dependencies must be provisioned per worktree, and a worktree missing them fails in ways that look like code defects — tests asserting a port that differs, a service tier that differs, an empty credential.
Ports and containers collide. A per-worktree port derived from the directory name is not collision-free, and a command that reads its port from the shell rather than the local environment file will happily bind the primary checkout's port — at which point someone else's browser is talking to your code and writing to your database.
Shared repository state is still shared. The object store, the recorded conflict resolutions, and anything in the common git directory are common to all worktrees.
See also13
Environment Variable
A named value in a process's environment, inherited by its children — the standard configuration channel.
Systems & Tooling23 connections
Port
The numeric endpoint a network service listens on, and a scarce shared resource on a developer machine.
Systems & Tooling19 connections
Subagent
A model instance spawned by another to handle a scoped task with its own context.
Agents & Language Models11 connections
Fan-Out and Fan-In
Splitting work across parallel workers and recombining their results.
Agents & Language Models11 connections
Token Budget
The finite allowance of model usage a task may consume, and the design decisions it forces.
Agents & Language Models20 connections
Shell
The interactive command interpreter, and a programming language with unusually sharp edges.
Systems & Tooling24 connections
Version Control
A system recording the history of a project's files, enabling branching, merging, and recovery.
Version Control & Delivery26 connections
Race Condition
A defect whose occurrence depends on the relative timing of concurrent operations.
Testing & Verification36 connections
Detached HEAD
The Git state in which the current checkout points directly at a commit rather than a branch, harmless for looking around but a trap for new work, since commits made there belong to no branch and can quietly disappear.
Version Control & Delivery11 connections
Git Hook
Scripts Git runs automatically at points such as committing or pushing, used to check formatting and messages locally, and on servers to enforce policy or trigger deploys.
Version Control & Delivery15 connections
Git Stash
Git's shelf for uncommitted work, which clears the working tree so you can switch tasks, and the reasons a throwaway commit or a second worktree is often the better shelf.
Version Control & Delivery10 connections
Shallow Clone
Ways to fetch less than a whole Git repository, by cutting history, deferring file contents, or checking out only some directories, and what each breaks.
Version Control & Delivery8 connections
Gitignore
The file of patterns telling Git which files to leave untracked, such as build output, dependencies, editor clutter, and local secrets, along with the traps of files that were already tracked and secrets already committed.
Version Control & Delivery12 connections
Linked from11
- ContainerizationSystems & Tooling
Packaging an application with its dependencies into an isolated, reproducible runtime unit.
- Detached HEADVersion Control & Delivery
The Git state in which the current checkout points directly at a commit rather than a branch, harmless for looking around but a trap for new work, since commits made there belong to no branch and can quietly disappear.
- Fan-Out and Fan-InAgents & Language Models
Splitting work across parallel workers and recombining their results.
- Git HookVersion Control & Delivery
Scripts Git runs automatically at points such as committing or pushing, used to check formatting and messages locally, and on servers to enforce policy or trigger deploys.
- Git StashVersion Control & Delivery
Git's shelf for uncommitted work, which clears the working tree so you can switch tasks, and the reasons a throwaway commit or a second worktree is often the better shelf.
- Multi-Agent OrchestrationAgents & Language Models
Coordinating several model instances on one body of work, each with its own context.
- PortSystems & Tooling
The numeric endpoint a network service listens on, and a scarce shared resource on a developer machine.
- Race ConditionTesting & Verification
A defect whose occurrence depends on the relative timing of concurrent operations.
- Shallow CloneVersion Control & Delivery
Ways to fetch less than a whole Git repository, by cutting history, deferring file contents, or checking out only some directories, and what each breaks.
- SubagentAgents & Language Models
A model instance spawned by another to handle a scoped task with its own context.
- Version ControlVersion Control & Delivery
A system recording the history of a project's files, enabling branching, merging, and recovery.