One .git, Five Checkouts: How git worktree Works Under Your Parallel Agents

One .git, Five Checkouts: How git worktree Works Under Your Parallel Agents

The git worktree feature allows multiple agents to work on separate tasks within the same repository. When five coding agents are started on five distinct tasks, they each receive their own worktree copy of the repository, resulting in five separate folders, branches, and terminals. Despite this, all commits and branches created by these agents are stored in the same object store and can be accessed through the same ref list.

To demonstrate this, a throwaway repository with one initial commit is created. Five linked worktrees are then added, each with its own branch named "hermes/task-1", "hermes/task-2", and so on. The `git worktree list` command shows a total of six worktrees – one main worktree and five linked worktrees.

Git directories are stored differently in the main repository and linked worktrees. In the main repository, .git is a directory, while in linked worktrees, it is a one-line text file containing a git directory reference. Each linked worktree has two git directories: a private folder inside the main repository and a shared directory.

Per-worktree ownership includes the HEAD, index, and refs/bisect, allowing each agent to work independently on its task without affecting others. Shared items include pseudorefs (except refs/bisect, refs/worktree, and refs/rewritten), config, hooks, and files on disk. When a commit is made in one worktree, it becomes visible in all other worktrees due to shared refs and objects.

Branches are shared between worktrees; attempting to switch to a branch from another worktree fails. Agents can still interact with each other's branches, but doing so may result in mismatched files and indices, causing Git to refuse the operation unless the --force option is used. Each task initiated in Hermes receives its own unique branch, ensuring no two tasks share the same branch.