Skip to main content
When an automated loop or CI job needs to try bold changes, something must keep the main codebase safe. That something is a worktree — a separate working copy where experiments can run without risking the main repository. What is a worktree?
  • A worktree is a separate working copy of the same Git repository.
  • Every worktree lives in its own folder with its own checked-out files.
  • Worktrees share a single repository history stored in the main .git directory.
  • Each worktree contains a small .git file (not a directory) that points back to the shared git data (for example, a gitdir: reference into .git/worktrees/...).
Because the history is shared, creating a worktree is fast and storage-efficient. Think of a worktree like a scratch copy of a shared document: you can experiment locally without duplicating the entire project history.
The image illustrates the concept of "Worktrees" in a Git repository, showing how a main repo with all history can be linked to multiple worktrees, which are fast and project-connected.
How the original repo and worktree relate
  • The original repository (the main folder) stays put and untouched while the worktree is the place for messy or experimental work.
  • Changes made inside a worktree do not affect the original until you commit, merge, and push from that worktree.
The image illustrates a concept of "Worktrees" with a central source branching into an "Original" version that "Stays put" and a "Scratch copy" for "Messy work."
Why use a separate copy?
  • Some experiments succeed and some fail. Running experiments directly in the main code risks breaking the primary branch.
  • A worktree gives you an isolated place to make large changes, run tests, and iterate, without endangering the main codebase.
The image compares working straight on the main code versus inside a worktree, highlighting the risks of breaking everything versus the safety of the main code.
Common git worktree operations Below are the most commonly used git worktree commands for creating, listing, removing, and cleaning up worktrees. Example workflows Create a new worktree and branch:
List all worktrees and where they live:
Run multiple worktrees side-by-side (no file clashes because each has its own working directory):
Remove a worktree when it’s done:
Git protects you from accidental deletion: it will refuse to remove a worktree that contains modified or untracked files.
If you intentionally want to discard a worktree and all its changes, add --force:
If you manually delete a worktree folder from disk but Git still lists it, clear stale entries with:
Worktrees share the same repository history (the main .git) while keeping separate working trees. The small .git file inside each worktree points Git back to the shared data, which is why creating a worktree is inexpensive.
The payoff
  • If a try fails, the usual cost is simply removing the worktree. The main repository remains clean.
  • Worktrees make automated experiments and hands-off loops safe: failed tries are disposable, and multiple experiments can run concurrently without interfering with each other.
The image illustrates the concept of "Worktrees," showing a comparison between a "Messy copy" and the "Main code" that is "clean and safe," with an arrow labeled "Remove --force" suggesting a process to maintain safety.
Quick recap
  • A worktree is a separate working copy that shares the repository history.
  • Use git worktree add to create one, git worktree list to display them, and git worktree remove to delete when finished.
  • Add --force to discard a worktree with local changes, and run git worktree prune to clean up stale entries.
  • Multiple subagents or experiments can run in parallel without clashing; failed attempts are cheap to throw away.
The image is a recap slide explaining Git worktree commands, including how to add, list, and remove worktrees. It highlights using --force and mentions multiple worktrees can run at once while keeping the main branch clean.
Links and references

Watch Video