Skip to main content

Git worktrees

Summary: A Git worktree lets one repository have multiple working directories at the same time, with each directory checked out to its own branch.

At a glance​

QuestionAnswer
What is it?Another working directory attached to one Git repository
Why use it?Work on branches in parallel without stashing or recloning
What is shared?Git object database and repository history
What is separate?Working files, index, and checked-out branch

How it works​

  • The main repository remains the shared Git repository.
  • Each worktree has its own directory and checked-out branch.
  • Commits are available to every worktree because they share repository history.
  • A branch checked out in one worktree cannot normally be checked out in another at the same time.

Common commands​

git worktree add ../feature-a feature-a
git worktree list
git worktree remove ../feature-a
git worktree prune

Create a new branch and worktree together when the branch does not exist:

git worktree add -b feature-a ../feature-a main

Parallel work​

Separate worktrees let people or tools work on different branches simultaneously:

one repository
├── main worktree      -> main
├── feature-a worktree -> feature-a
└── feature-b worktree -> feature-b

Coding agents can use one worktree each, which prevents their uncommitted edits from colliding in the same directory. Git worktrees provide the isolation; they do not coordinate the agents or review their changes.

When worktrees edit the same file​

Two worktrees contain separate physical copies of the same file, so agents do not overwrite each other's uncommitted changes while they work.

The conflict appears later when their branches are merged:

ChangesResult
Different linesGit may merge automatically
Same linesGit may report a merge conflict
Different implementations of the same behaviorA human must choose or combine them

Worktrees prevent live filesystem collisions. They do not prevent logical conflicts when branches are integrated.

worktree A -> branch A -> agent A
worktree B -> branch B -> agent B
          |
        merge or rebase
          |
           main

After one branch is merged, the other worktree remains based on its previous history. Update it with either:

git rebase main

or:

git merge main

Then resolve conflicts, run tests, and continue the review.

Remember: Worktrees isolate the work while it is happening; Git still reconciles the work when branches come back together.

Remember​

  • A worktree is a directory attached to an existing repository, not a second clone.
  • Each worktree should represent a distinct branch.
  • Remove unused worktrees and run git worktree prune after manual deletion.
  • Worktrees provide isolation, not task orchestration.

Sources​