What is a worktree?

One repository checked out in several folders at once: the commits and branches shared, the HEAD, staging and files of each its own.

A worktree is a folder where a repository is checked out. Every repository has one, the folder git clone or git init made: the main worktree. git worktree add gives it more, called linked worktrees, each in a folder of its own with a branch of its own checked out. They are not copies. There is still one repository, and each linked worktree is a checkout of it.

What they share is everything the repository holds: its commits, its branches and tags, its configuration, its stashes. What each has to itself is what makes it a place to work: its own HEAD, its own staging area, and its own files. A commit made in any of them is in all of them at once, because the branch it moves is the same branch.

  1. From the main worktree: HEAD is main, and README.md has a change not yet committed.

  2. The same repository from a linked worktree: the same commits and branches, but its HEAD is feature and its changed file is another.

  3. Commit there, and feature moves to E for every worktree. The main worktree's HEAD and its README.md change are where they were.

One branch, one worktree

Git checks a branch out in one worktree at a time, and refuses to check it out in a second. Two folders moving the same branch would each find the other’s commits under their files. A worktree can also be on no branch at all, on a detached HEAD, which is how a throwaway checkout for an experiment is usually made.

That is what makes worktrees the usual way to give a coding agent a branch to itself: it works in its folder, you work in yours, and neither switch disturbs the other.

Where Git keeps track of them

A linked worktree’s .git is a file rather than a folder, pointing back into the repository, where Git keeps a small record of each linked worktree. Delete the folder by hand and the record is left behind until Git prunes it, which it does on its own after a while, or at once with git worktree prune. Locking a worktree, for one on a drive that is not always connected, keeps its record and stops it being moved or removed.

In Innesta, worktrees have a section of their own in the sidebar.