Skip to content
Velloreth
Developer Tools 6 min read

Git Worktrees: Working on Two Branches at Once

Worktrees let you check out multiple branches in separate directories from one repository. Learn when they beat stashing.

By

The problem

You are halfway through a feature when a colleague asks you to review a pull request. You need their branch checked out, but your working tree has uncommitted changes.

The options:

  • Stash your work, switch, review, switch back, unstash. Works, but the stash is easy to forget and the switch is disruptive.
  • Commit your work to a temporary branch. Safer, but you have to remember to undo it.
  • Clone the repository again. Works, but it is a separate repository, so you have to fetch and push separately.
  • Worktree. Check out the other branch in a separate directory, from the same repository.

What a worktree is

A worktree is an additional working directory attached to the same repository.

git worktree add ../review-branch origin/feature-x

This creates ../review-branch with feature-x checked out. Your original directory is untouched.

project/          ← main worktree, on main
review-branch/    ← linked worktree, on feature-x

Both share the same .git object database and refs. A commit in one is immediately visible in the other.

The commands

Add a worktree for an existing branch:

git worktree add ../path branch-name

Add a worktree with a new branch:

git worktree add -b new-branch ../path

Add a worktree in detached HEAD state:

git worktree add --detach ../path origin/main

List worktrees:

git worktree list
# /home/user/project        a1b2c3d [main]
# /home/user/review-branch  e4f5g6h [feature-x]

Remove a worktree:

git worktree remove ../path

Force removal with uncommitted changes:

git worktree remove --force ../path

Prune stale entries:

git worktree prune

If you delete a worktree directory manually, the metadata remains. prune cleans it up.

Why they are cheap

A worktree shares the object database. It does not duplicate the history, the objects, or the refs. It stores only its own working files and its own index.

This is the key difference from a clone. A clone is a separate repository: it has its own objects, its own refs, and its own remotes. You must fetch and push in each clone separately. A worktree shares all of that, so a commit in one worktree is immediately visible in the others.

The branch constraint

Two worktrees cannot check out the same branch.

git worktree add ../other main
# fatal: 'main' is already checked out at '/home/user/project'

This is deliberate. Two working trees on the same branch would conflict, because a commit in one would change the branch that the other has checked out.

The workaround is a detached HEAD, which is fine for reviewing or building.

git worktree add --detach ../review origin/main

Common workflows

Review a pull request:

git fetch origin pull/123/head:pr-123
git worktree add ../pr-123 pr-123
cd ../pr-123
npm install && npm test

Your own work stays in place, and the review is in a separate directory.

Compare two branches:

git worktree add ../v1 v1.0.0
git worktree add ../v2 v2.0.0
diff -r ../v1/src ../v2/src

Run a long build while working:

git worktree add ../build-branch release
cd ../build-branch
npm run build   # runs while you keep working in the main directory

Test a hotfix against production:

git worktree add ../hotfix main
cd ../hotfix
# apply and test the fix

Keep a documentation branch checked out:

git worktree add ../docs docs

Worktree versus alternatives

WorktreeStashClone
Separate directoryYesNoYes
Shares historyYesN/ANo
Parallel workYesNoYes
Needs separate fetchNoNoYes
Disk costLowNoneHigh
Easy to forgetNoYesNo

Use a worktree when you need two branches checked out at once, or when a long-running process needs its own directory.

Use a stash for a quick context switch where you will return in minutes.

Use a clone when you need a genuinely separate repository, such as a fork or a different remote.

Gotchas

The branch constraint. Two worktrees cannot share a branch. Use --detach for read-only work.

Submodules. A worktree does not automatically initialise submodules. Run git submodule update --init in the new worktree.

Ignored files. A worktree has its own working directory, so files that are ignored and not committed (like .env) are not present. You must recreate them.

Build artifacts. Each worktree has its own node_modules and build output, so a fresh worktree needs its own install.

Editor state. Your editor may not know about the new directory. Open it as a separate project.

Stale metadata. Deleting a worktree directory manually leaves metadata behind. Run git worktree prune.

Worktrees in CI and tooling

Worktrees are useful beyond the developer’s machine.

Parallel test runs. A CI job that needs to test several branches can create a worktree per branch rather than cloning the repository repeatedly. Since the objects are shared, the setup is fast.

Documentation builds. A site that builds from a branch can keep a worktree checked out at the documentation branch, so the build does not disturb the main working tree.

Long-running processes. A dev server, a watcher, or a database migration can run in its own worktree while you keep editing in the main one. This is the most common practical use: the process holds files open, and switching branches in the same directory would break it.

Reviewing generated output. A worktree lets you build a branch and inspect the output without touching your own build artifacts.

The common thread is isolation: a worktree gives a process or a task its own directory, backed by the same repository, without the cost of a clone.

Practical guidance

  • Use a worktree to review a pull request without disturbing your work.
  • Use --detach for read-only work on a branch that is checked out elsewhere.
  • Run git worktree list to see what exists.
  • Remove with git worktree remove, not rm -rf.
  • Run git worktree prune after a manual delete.
  • Recreate ignored files like .env in a new worktree.
  • Install dependencies in each worktree.
  • Prefer a worktree over a stash for parallel work.

For the related guides, see git-stash-guide and git-branching-strategies. For the broader context, git-merge-vs-rebase and code-review-checklist.

Quotable summary

A worktree is an additional working directory attached to the same repository, each with its own checked-out branch, and they share the object database and refs so they are cheap and stay in sync automatically. Worktrees solve the problem of needing two branches checked out at once, which stash and commit cannot, and they are the natural tool for reviewing a pull request while keeping your own work in place. Two worktrees cannot check out the same branch, so use —detach for read-only work. Remove a worktree with git worktree remove rather than deleting the directory, and run git worktree prune to clean up stale metadata. Unlike a clone, a worktree shares history, so a commit in one is immediately visible in the others.

Frequently asked questions

What is a git worktree?
An additional working directory linked to the same repository. Each worktree has its own checked-out branch and its own working tree, but they share the object database and refs.
How is a worktree different from a clone?
A clone is a separate repository with its own objects and refs, so it needs its own fetch and push. A worktree shares the same repository, so commits, branches, and remotes are immediately visible in all worktrees.
Can two worktrees check out the same branch?
No. Git prevents it, because two working trees on the same branch would conflict. Each worktree must be on a different branch, or in a detached HEAD state.
How do I remove a worktree?
Use git worktree remove <path>. If the worktree has uncommitted changes, add --force. If the directory was deleted manually, use git worktree prune to clean up the metadata.
When should I use a worktree instead of a stash?
When you need to work on two branches at the same time, such as reviewing a pull request while your own work stays in place. A stash is for a quick context switch; a worktree is for parallel work.
Do worktrees take a lot of disk space?
No. They share the object database, so a worktree only stores its own working files. The repository history is not duplicated.