Friday, November 20, 2026

Guide

Git Worktree vs Branch: When You Need a Worktree

They are not alternatives. A branch is a name for a line of commits; a worktree is a folder where one branch is checked out. The real choice is between switching branches inside one folder and giving each branch its own folder.

Updated

Worktree vs branch at a glance

BranchWorktree
What it isA movable name that points at a commitA working directory with its own HEAD and index, attached to one repository
Where it livesA ref inside .git (refs/heads/<name>)A folder on disk, plus a small admin folder under .git/worktrees/<name>
What it separatesA line of historyFiles on disk, the staging area and what is checked out
Cost to createAlmost nothing: one refA full checkout of tracked files; the commit history is shared, not copied
How many at onceAs many as you like, one checked out per folderAs many as you like, each with a different branch (or a detached HEAD)
Creategit branch <name> or git switch -c <name>git worktree add <path> <branch>
Clean upgit branch -d <name>git worktree remove <path>, then git worktree prune for folders deleted by hand

What a branch is

A Git branch is a pointer: a name stored in the repository that refers to one commit and moves forward each time you commit on it. Creating a branch copies no files, which is why branches are cheap enough to make for every task.

A branch on its own has no files you can edit. To work on it you check it out, and in a plain clone there is exactly one place to do that: the repository's single working directory. git switch other-branch rewrites the files in that folder to match the other branch. Whatever you had open, built or running there now sees different code.

What a worktree is

A worktree is a working directory: the files you edit, plus the HEAD that says what is checked out and the index that holds what is staged. Every repository already has one, the main worktree. git worktree add creates more, called linked worktrees, each in its own folder and each with its own branch checked out.

Linked worktrees are not copies of the repository. They share one object store, so every commit, branch, tag, remote and stash is visible from all of them, as are the repository's config and hooks. What each keeps to itself is its files on disk, its HEAD, its index, and any untracked or ignored files in its folder. A linked worktree's .git is a small file pointing back to the main repository rather than a full directory.

How branches and worktrees fit together

Every worktree has a branch checked out, or a detached HEAD at a specific commit. The rule that connects the two: a branch can be checked out in only one worktree at a time. If feature-x is checked out in one folder, Git refuses to check it out in a second, and refuses to delete it with git branch -d while it is checked out there. Recent versions of git branch mark branches checked out in other worktrees with a +.

The rule exists so that two folders never move the same branch underneath each other. In practice it means one worktree per task, one branch per worktree. If you need to look at a branch that is busy elsewhere, add a worktree with --detach at that commit, or make a new branch from it.

When switching branches is enough

  • You work on one thing at a time and your tree is clean, or a quick commit or stash makes it clean, when you move.
  • Builds and test runs are fast, so rebuilding after a switch costs little.
  • Nothing long-running (a dev server, a test suite, an agent session) depends on the files staying put.

In that case one folder and git switch is simpler: there is one set of dependencies to install, one editor window and nothing to clean up afterwards.

When a worktree is the better choice

  • You are interrupted mid-change. A hotfix or a review comes in while your branch is half-edited. Add a worktree for the hotfix and leave your work exactly where it is, with no stash to remember.
  • Something is running on one branch. A long test suite, a build or a local server keeps running against its own files while you keep editing another branch elsewhere.
  • You want two versions side by side. Run the old and new behaviour at the same time, or diff folders in your editor, instead of switching back and forth.
  • Several coding agents work in parallel. Agents in one folder overwrite each other's files and staged changes. A worktree per agent gives each its own files, index and branch while they share one history, which is the pattern the rest of this site builds on.

The worktree commands you will use

# Check out an existing branch in a new folder
git worktree add ../myrepo-feature-x feature-x

# Create a new branch from main and check it out in a new folder
git worktree add -b hotfix ../myrepo-hotfix main

# Look at a commit without tying up a branch
git worktree add --detach ../myrepo-review <commit>

# See every worktree, its commit and its branch
git worktree list

# Remove a worktree (refuses if it has changes; --force overrides)
git worktree remove ../myrepo-hotfix

# Clear records of worktree folders that were deleted by hand
git worktree prune

If you leave out the branch, git worktree add <path> uses the folder's name as the branch name and creates that branch from your current HEAD if it does not exist yet. git worktree lock keeps a worktree on removable or network storage from being pruned, and git worktree move relocates one without breaking its link.

What a new worktree does not bring with it

A worktree checks out tracked files only. Anything Git ignores stays behind in the folder it was created in, so each new worktree usually needs its own setup:

  • Installed dependencies such as node_modules or a virtualenv, and build output.
  • Local config that is not committed, such as .env files.
  • Anything outside the repository: two worktrees running the same dev server still compete for one port, one local database and one cache.
  • Submodules: Git's own documentation describes submodule support in worktrees as incomplete, so check how your submodules behave before relying on it.

The stash is shared, too: a stash made in one worktree shows up in git stash list in every other.

Worktree vs a second clone, and vs stash

A second clone also gives you another folder, but it is a separate repository: its own copy of the history, its own remotes and config, and its own branches that you sync by pushing and fetching. A worktree shares one repository, so a commit made in one worktree is instantly visible from the others and nothing is downloaded twice.

Stash shelves uncommitted changes so you can switch branches in the same folder. It suits a quick detour. A worktree suits work that needs to stay open, built or running while you do something else.

Check the details

Read next