Git worktree: a second checkout of the same repository
A git worktree is an additional working directory linked to an existing repository, with its own checked-out branch, index and files, while sharing the repository's history and objects. `git worktree add <dir> -b <branch>` creates one in seconds, which makes it the natural unit for parallel agent tasks: one task, one worktree, one branch.
At a glance
Shares
History, objects, remotes, config
Has its own
Branch, files on disk, index
Created with
git worktree add <dir> -b <branch>
Why fleets use it
Parallel tasks without clones and without collisions
Why not let every agent work in the same checkout?
Because two agents editing the same files at once overwrite each other, and an
agent that runs the tests sees the other agent’s half-finished changes. A
worktree per task gives each one a clean copy of the code on its own branch, and
the work survives on that branch when the directory is removed. Clones would do
the same but copy the whole history each time; worktrees share it.
What is the catch for automated tools?
A worktree’s .git is a small file that points to the real git directory, and
whoever can write the worktree can change where it points. A tool that runs git
in an agent’s worktree afterwards should restore that pointer first and disable
anything in git config that runs programs, or it may end up executing code the
agent planted.
Check it yourself
git worktree add ../task-1 -b task-1
git worktree list
git worktree remove ../task-1 # the branch task-1 stays
Worktrees give you
Parallel work on one repository, no full clone per task
A branch per task that keeps the work after the directory is gone
Your own checkout stays untouched
Mind that
A branch can be checked out in only one worktree at a time
Removing a worktree with --force deletes uncommitted work
Its .git is a file pointing elsewhere, which tools must not trust blindly