A git worktree is an additional working directory attached to one repository. Each worktree checks out its own branch and keeps its own HEAD and index, while commits, branches, tags, remotes and config are shared through a single object database. Switching branches becomes cd, which is what makes running several coding agents at once safe.
- One repository, several working directories, one shared object database.
- Each worktree checks out its own branch. Git refuses to check one out twice.
- Objects, branches, tags, remotes, hooks and the stash are shared.
HEAD, the index and ignored files are not. - In a linked worktree,
.gitis a file containing a pointer, not a directory. - Switching branches becomes
cd, with no stashing and no rebuild. - That is what makes parallel agents safe rather than merely fast.
What a worktree actually is
A git worktree is an additional working directory attached to an existing repository. You create one with git worktree add, it checks out a branch of its own, and it shares every commit, branch, tag and remote with the directory you created it from. A normal clone is one repository plus one working directory. A worktree splits that: one repository, many working directories.
BEFORE AFTER
~/code/app/ ~/code/app/ (main)
.git/ <- directory .git/ <- the repository
src/ src/
~/code/app-auth/ (feature/auth)
one directory, .git <- a FILE, not a directory
one branch at a time src/
~/code/app-search/ (feature/search)
.git
src/In the new directory, .git is not a directory. It is a one-line text file holding a pointer back into the original repository, and that indirection is the entire trick.
$ cat ../app-auth/.git
gitdir: /Users/you/code/app/.git/worktrees/app-auth
$ git -C ../app-auth rev-parse --git-dir
/Users/you/code/app/.git/worktrees/app-auth
$ git -C ../app-auth rev-parse --git-common-dir
/Users/you/code/app/.gitThose last two commands are the clearest statement of the model there is. Every worktree has a private git directory holding its own HEAD and index, and a common git directory holding everything worth sharing. That split is the whole feature.
What is shared and what is private, per the git-worktree manual.
| Thing | Shared? | Consequence |
|---|---|---|
| Commits and objects | Yes | No duplicated history; a worktree costs a checkout, not a clone |
| Branches and tags | Yes | A commit made in one is immediately visible in all |
| Remotes and fetches | Yes | Fetch once, every worktree sees it |
Repository git config | Yes | Unless you enable extensions.worktreeConfig |
| Hooks | Yes | One post-checkout hook serves every worktree |
| The stash | Yes | One shared stack; git stash list is identical everywhere |
HEAD, index, logs/HEAD | No | Each worktree has its own checkout state |
refs/bisect, refs/worktree, refs/rewritten | No | A bisect or rebase in one does not disturb another |
| Working files | No | That is the point |
node_modules, .env, build output | No | Ignored files are not tracked, so git cannot check them out |
Look inside one
The private half lives under .git/worktrees/<name>/ in the original repository. It is small, it is plain files, and reading it removes most of the mystery.
$ ls .git/worktrees/app-auth/
commondir
gitdir
HEAD
index
logs
ORIG_HEAD
refs
$ cat .git/worktrees/app-auth/commondir
../..
$ cat .git/worktrees/app-auth/gitdir
/Users/you/code/app-auth/.gitThe two files that hold a worktree together.
| File | Lives in | Points at |
|---|---|---|
.git | The worktree directory | The admin directory in the repository |
gitdir | The admin directory | Back at the worktree .git file |
commondir | The admin directory | The shared repository (usually ../..) |
The one rule that surprises people
Git will not check out the same branch in two worktrees. You meet this within about five minutes of starting.
$ git worktree add ../app-auth feature/auth
Preparing worktree (checking out 'feature/auth')
fatal: 'feature/auth' is already used by worktree at '/Users/you/code/app-auth'
# On Git 2.42 and older the same refusal read:
# fatal: 'feature/auth' is already checked out at '/Users/you/code/app-auth'The wording was changed in Git 2.43 because a branch being bisected or rebased is protected by the same code path, and calling that "checked out" confused people. The behaviour is unchanged: one branch, one worktree.
It is a feature rather than a limitation. Two directories on one branch with different working states means two places committing to a single ref, which diverges the moment either of them commits. Git declines to create that situation.
What to do instead.
| You want | Use |
|---|---|
| A new branch to work on | git worktree add -b feature/x ../app-x |
| A read-only look at a tag or commit | git worktree add --detach ../app-v1 v1.0.0 |
| A local branch tracking a remote one | git worktree add -b pr-42 ../app-r origin/pr-42 |
| To override the refusal anyway | --force, and you will regret it |
Worktree, clone, or just switch branches
Three ways to have a second thing checked out. They are not interchangeable, and the differences are mostly about cost and about whether the two things can be worked on at the same time.
The same job, three arrangements.
| Switch branches | Second clone | Worktree | |
|---|---|---|---|
| Disk cost | Nothing | History plus files, twice | Files only |
| Creation time | Instant | A full clone | A checkout |
| Remotes to keep in sync | One | Two | One |
| Commit visible in the other | n/a | Only after a push and fetch | Immediately |
| Two things at once | No | Yes | Yes |
| Branch lists drift apart | n/a | Yes | No |
| Dependencies installed | Once | Once per clone | Once per worktree |
Switching is right for sequential work, which is most work. A second clone is right when you genuinely want an independent repository, for example a build agent that should not see your local refs. A worktree is right when you want the same repository in two places at once, which is the case that used to be rare.
Why it suddenly matters
Before coding agents, the case for worktrees was moderate. Review a colleague branch without stashing. Keep a long build running while you work elsewhere. Real, but a convenience, and stashing covered most of it.
An agent changes the arithmetic completely, because it edits files on its own while you are not watching. Two agents in one working directory is not a workflow problem, it is a correctness problem. They write the same files with no coordination, one overwrites the other, and neither reports an error. You find out later, in a diff that does not make sense, and you cannot reconstruct which agent did what.
Three concurrent tasks, two arrangements.
| One directory | One worktree each | |
|---|---|---|
| Agents editing simultaneously | Collide silently | Isolated |
| Test runs | Interfere | Independent |
| Reviewing a diff | Everything mixed together | One branch, one diff |
| Abandoning one task | Untangle it by hand | git worktree remove |
| Merging | Untangle first, then one PR | Three ordinary pull requests |
| Disk cost | One checkout | N checkouts |
Questions people ask
A second working directory backed by the same repository. Each worktree checks out its own branch and keeps its own HEAD and index, while commits, branches, tags and remotes are shared through one object database.
A clone duplicates the entire history and gets its own remotes, so the two repositories drift apart and a commit in one is invisible in the other until you push and fetch. A worktree shares the repository, so it is far cheaper to create and a commit in one is visible in all of them immediately.
No. Git refuses with "is already used by worktree at", because two directories committing to one ref diverge as soon as either commits. Create a new branch with -b, or use --detach for a read-only look at a commit.
That is how a linked worktree points back at its repository. The file contains one line, gitdir: followed by the path to the worktree admin directory under .git/worktrees. Run git rev-parse --git-common-dir to see the shared repository it resolves to.
No. Worktrees carry tracked files only, and node_modules and .env are gitignored, so git does not have them to check out. You install dependencies and copy environment files per worktree, usually from a script or a post-checkout hook.
Yes. The stash is a single shared stack, so git stash list shows the same entries in every worktree. That is confusing enough in practice that commits on a throwaway branch are a better habit once you have several worktrees.
They are the mechanism that makes it safe. Two agents in one working directory overwrite each other with no error and no warning. One worktree each gives every agent its own files, its own branch and its own diff.
The checkout is cheap because the object database is shared, so you pay for source files and nothing else. The real cost is per-worktree dependency directories, which a content-addressed package manager such as pnpm reduces to hard links.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.
- git-worktree manual
- Pro Git book
- Git 2.43 release notes the reworded in-use message