Git Worktree

Programmers usually store their program code with a tool called Git. Git keeps track of every change to the files and can restore any earlier state. Normally there is exactly one folder in which one works, and only one version of the project resides there at any time. A Git worktree is another such working folder, but one that belongs to the same stored project history. One then has two or more folders on the hard drive in which different versions of the same project are open at the same time. The command for this is called “git worktree add”.

What a second working folder is good for

Software projects are almost always maintained along several lines of development. One line contains the stable version for users, another the new, still-unfinished features. In Git terminology these lines are called branches. Without worktrees, one always has to switch within the single folder: Git then exchanges all the files so that the desired branch becomes visible.

This switching is the actual pain point. It only works if there are no half-finished changes pending. Anyone in the middle of a task who is urgently supposed to fix a bug in the stable version first has to stash their work away. With a second worktree, this becomes completely unnecessary: the bug is fixed in one folder, while the work in progress stays untouched in the other.

A second advantage is time. Large projects need a new build process after every switch, because the computer first has to turn the program code into a runnable program. This can take minutes. Each worktree keeps its own intermediate results, so both stay immediately ready to run. One can even run two versions in parallel and compare them directly.

One repository, several folders

Git stores the entire project history in a hidden subfolder named “.git”. All the old versions are kept there in compressed form. The files one actually edits are merely an unpacked snapshot taken from it. A worktree uses exactly this one repository, but unpacks a different snapshot.

The difference from a simple copy of the folder is therefore substantial. A copy would have its own, separate history, and changes would have to be laboriously transferred back and forth. With worktrees, the history is shared: a commit made in one folder is immediately visible in the other. The storage requirement is also lower, because the repository only exists once.

To prevent things from getting mixed up, one rule applies: the same line of development may not be open in two worktrees at the same time. Git refuses this and reports an error. Another common mistake is simply deleting a worktree that is no longer needed. Git continues to keep track of the folder and afterwards needs the command “git worktree prune” to clean up the reference.

Worktrees in developers' everyday work

The command has been part of Git itself since 2015, so nothing needs to be installed separately. Nevertheless, many developers don’t know it, because switching is enough for small projects. But anyone working on very large codebases, such as operating systems or browsers, uses worktrees regularly. Automated test systems, too, often set up their own worktree for each state to be checked.

Recently, worktrees have been showing up in the news mainly in connection with AI coding assistants. Such assistants work on a project independently over many steps. If several assistants are given tasks at the same time, they would overwrite each other’s files in a single folder. Each one therefore gets its own worktree as a shielded workspace, and in the end a human checks which results get adopted.