How a second worktree shares one repository

Table of Contents

• Introduction
• What is git worktree add?
• Watch it happen
• Before and after
• When to use one
• Is it safe?
• How to undo it
• Try it on your repository
• Common questions
• Summary
• Next steps
• Related commands

Introduction

The usual way to look at another branch is to stash, switch, look, switch back, unstash. git worktree add skips all of that by checking the other branch out into its own directory next to your current one. Both directories share the same .git, so a commit in one is visible in the other immediately. It has become a lot more popular lately, since it's how you let several AI coding agents work on the same repository without stepping on each other.

In this article, we'll:

1. Watch git worktree add check feature out into a second directory
2. See that the main worktree is untouched
3. Cover when a worktree beats a stash or a second clone, and how to remove one

What is git worktree add?

git worktree add <path> <branch> creates the directory <path>, checks <branch> out into it, and registers it in .git/worktrees/. The new directory has its own working files, its own index and its own HEAD, but no object database of its own: it reads and writes the main repository's. A branch can be checked out in only one worktree at a time.

Watch it happen

Our sample repo has feature to be checked out in a second working directory. Here's git worktree add ../hotfix-tree feature from the main worktree, which has main checked out:

1. Before: the main worktree, your_project, has main checked out, with main and HEAD on 8c02d5b and feature on 1117a34. No commits or branches change during the command.
2. Git creates ../hotfix-tree, checks the existing feature branch out into it (its own HEAD is at 1117a34) and registers it, so the repository now has two worktrees: your_project on main and hotfix-tree on feature. That's also why feature can't be checked out anywhere else while this worktree exists.

Before and after

The commit graph is the same before and after. What changed is on disk: a new directory ../hotfix-tree with feature's files in it, and an entry under .git/worktrees/. Git's output shows it checking the branch out:

* 1117a34 (feature) Add search tests
* e5869f0 Fix typo in search box
* fc19889 Add search box
| * 8c02d5b (HEAD -> main) Update dependencies
| * a0b2db3 Add user settings page
|/  
* 96c4fc2 Fix header layout
* ae65976 Add login page
* 3e1ffe4 Add project skeleton
* 4114b2c Initial commit

* 1117a34 (feature) Add search tests
* e5869f0 Fix typo in search box
* fc19889 Add search box
| * 8c02d5b (HEAD -> main) Update dependencies
| * a0b2db3 Add user settings page
|/  
* 96c4fc2 Fix header layout
* ae65976 Add login page
* 3e1ffe4 Add project skeleton
* 4114b2c Initial commit

HEAD is now at 1117a34 Add search tests
Preparing worktree (checking out 'feature')

git worktree list shows both directories and which branch each has. The git worktree documentation covers list along with lock, move and the other subcommands.

When to use one

• You need to run the tests on main while you keep editing on feature.
• You want to compare two branches side by side in an editor.
• Several agents or scripts need to work in the same repository at once, each on its own branch.
• A long build is running in one branch and you don't want to disturb it.

Most of the time the branch for the new worktree doesn't exist yet. git worktree add -b hotfix ../hotfix-tree creates hotfix at the current commit, 8c02d5b, and checks it out in the new directory in one go, while main stays checked out in your_project:

A second clone would also work, but it duplicates the object database and its branches drift from yours. A stash works for a quick look but not for two things happening at once.

Is it safe?

Adding a worktree creates a directory and some bookkeeping. Nothing in the history changes.

How to undo it

git worktree remove ../hotfix-tree

deletes the directory and the registration. Git refuses if the worktree has uncommitted changes, unless you add --force.

Here's that removal on our repository. hotfix-tree is clean, so Git deletes it and its registration, your_project keeps main checked out, and feature stays on 1117a34, free to be checked out again:

Try it on your repository

pip install git-sim
git-sim worktree add ../hotfix-tree feature

git-sim shows the second HEAD landing on the branch you name, and notes if that branch is already checked out somewhere.

Common questions

What is a git worktree?

A second working directory attached to the same repository, with its own checked-out branch, sharing the object database and refs with the main one.

What is the difference between a worktree and a clone?

A clone copies the whole repository and has its own branches and remotes. A worktree shares everything except the working files, so commits made in one are immediately visible in the other.

Can I check out the same branch in two worktrees?

No. Git refuses, because two working directories updating one branch would conflict. Create a second branch instead.

How do I remove a worktree?

git worktree remove <path>. If you deleted the directory by hand, git worktree prune cleans up the registration.

Summary

In this article, we watched git worktree add check a branch out into a second directory that shares the repository, saw that the main worktree was unaffected, and covered when a worktree fits better than a stash or a clone.

Next steps

git stash is the lighter tool for a quick look at another branch, and git branch creates the branch a new worktree usually needs.

Related commands

• git branch -d, to remove the branch once the worktree is gone
• git stash, the lighter alternative
• git checkout, switching within one worktree
• git branch, each worktree has one checked out
• git fetch, runs once for every worktree
• git status, runs independently in each worktree