Git worktree
git worktree lets one repository expose multiple working directories at the same time.
Instead of cloning the same repo again and again, you can keep one shared repository object store and open several branches in parallel.
This is especially useful when:
- you are fixing one bug while another feature is in progress
- you want a clean review branch without stashing current work
- multiple AI agents need isolated working directories
- you want to compare branches side by side
Why use it instead of another clone
The main benefits are:
- faster than recloning
- less disk usage than multiple full clones
- one shared repository history and object database
- each worktree still gets its own
HEAD, index, and working directory
In practice, it feels like “multiple checkouts from one repo”.
The basic commands
Create a new worktree from an existing branch
This creates a sibling directory ../docs-fix and checks out branch docs-fix there.
Create a new worktree and new branch in one step
This is the most common pattern for new work.
List all worktrees
Remove a worktree
Use prune when a worktree directory was deleted manually and Git still remembers it.
A practical workflow
Imagine your main repository is in ~/code/project:
Now you can:
- keep normal work in
project
- do feature work in
project-feature-a
- isolate a production fix in
project-login-fix
This is a much cleaner workflow than repeatedly stashing, rebasing, and switching branches in one directory.
Why it is useful for AI agents
For multi-agent coding, git worktree is often the simplest safe default.
Each agent can get:
- its own directory
- its own checked-out branch
- its own build artifacts and temp files
- much lower risk of stomping on another agent’s uncommitted changes
That makes worktree-based coordination much easier than sharing one checkout.
A simple pattern
Then assign one worktree per task or per agent.
Important rules
1. Do not check out the same branch in two worktrees
Git prevents most of this automatically, but the principle matters:
- one branch
- one active worktree
If two places both try to advance the same branch, you lose the isolation benefit.
2. Remove worktrees with Git when possible
Prefer:
instead of deleting the folder directly.
If you do delete it manually, follow up with:
3. Use worktree-specific config when needed
By default, the main .git/config is shared across worktrees.
If you need config that should exist only in one worktree, enable:
Then set per-worktree values with:
This is useful when different worktrees need different sparse-checkout or local behavior.
What is shared and what is separate
Shared
- repository objects
- most refs
- normal repository history
- main config by default
Separate per worktree
HEAD- index
- working directory contents
- some per-worktree refs and pseudorefs
- optional
config.worktree
That split is the reason worktrees are both lightweight and practical.
Good use cases
- parallel feature development
- hotfix branch alongside a bigger refactor
- multi-agent implementation lanes
- trying risky changes without disturbing the current checkout
- large repos where full reclones are wasteful
When a full clone is still better
Use a separate clone instead if you need:
- a fully separate Git config and credential context
- different remotes or fork wiring
- total isolation for experiments
- to work across very different repository states independently
Worktrees are excellent for same-repo parallelism, not for every kind of isolation.
Small but relevant Git 2.54 note
Today’s Git ecosystem update also included Git 2.54, which added a new experimental git history command for simpler history edits and made geometric repacking the default manual maintenance strategy.
That is useful context, but for day-to-day parallel work, git worktree is still the more immediately practical feature to master.
References
Last modified on August 31, 2026
