Creating

Introduction

A linked worktree is a second checkout of the same repository. It shares objects, refs, and config, but keeps its own HEAD, index, and files.

They suit parallel branches, review, hotfixes, and one checkout per agent.

Add a worktree

git worktree add ../hotfix hotfix
git worktree add ../next
git worktree add ../fix -b fix main

The first form checks out an existing branch. Without a branch, add checks out or creates the branch named after the path. -b creates a branch from a start point, HEAD by default. The path must be empty or missing.

See: git worktree add

Branch options

git worktree add --track -b topic ../topic origin/main
git worktree add -B reset ../reset main
git worktree add --orphan -b empty ../empty
git worktree add ../prev -

--track marks a start point as upstream; it is implied for a remote-tracking branch. -B resets an existing branch. --orphan starts an unborn branch with an empty index. A bare - means @{-1}, the previous branch.

See: git worktree options

Detached checkouts

git worktree add --detach ../review origin/main
git worktree add --no-checkout -b sparse ../sparse main

--detach leaves HEAD off any branch, so a review worktree cannot claim a branch. --no-checkout skips the initial checkout for sparse or custom setups.

See: git worktree options

Inspecting

List worktrees

git worktree list
git worktree list -v
git worktree list --porcelain

Output

AnnotationMeaning
barea bare repository entry
detachedHEAD is not on a branch
lockedprotected from prune, move, and remove
prunablethe worktree directory is missing

The default output shows the path, current commit, and branch or detached HEAD. -v adds lock reasons; --porcelain emits stable key value records for scripts. bare and detached appear in the default output; locked and prunable are appended.

See: List output format

Where worktrees live

cat ../hotfix/.git
# gitdir: /repo/.git/worktrees/hotfix

Shared state

SharedPer worktree
objects, refs, config, hooksHEAD, index, sparse patterns

Each linked worktree has a private directory under .git/worktrees/<id> holding its HEAD and index; its .git file points there. Objects, refs, config, and hooks stay shared.

See: gitrepository-layout

Managing

Remove a worktree

git worktree remove ../hotfix
git worktree remove --force ../dirty

remove deletes the directory and its admin entry, but leaves the branch and its commits. It refuses modified or untracked files; --force discards them. A locked worktree needs --force twice. The main worktree cannot be removed.

See: git worktree remove

Prune stale entries

git worktree prune -n -v
git worktree prune

prune removes admin entries whose worktree directory is gone, which happens after a manual rm -rf. -n reports without removing; -v names each entry. Automatic pruning runs from git gc after gc.worktreePruneExpire, three months by default.

See: gc.worktreePruneExpire

Lock a worktree

git worktree lock --reason "usb drive" ../hotfix
git worktree unlock ../hotfix

Locking prevents prune, move, and remove from touching the entry. Use it for worktrees on removable or network paths. add --lock locks at creation without a race window.

See: git worktree lock

Move and repair

Move

git worktree move ../hotfix ../hotfix-2

After a manual move

git worktree repair ../hotfix-2

move updates the admin files. If you move a directory by hand, the entry becomes prunable; run repair from the moved worktree, or in the main worktree with its new path. Main and submodule worktrees cannot be moved.

See: git worktree repair

Rules

One branch, one worktree

git worktree add ../other main
# fatal: 'main' is already used by worktree at '/repo'

A branch can be checked out in only one worktree; git checkout enforces the same rule. --force overrides it, but two checkouts invite lost commits. Use a detached worktree when the same commit is enough.

See: git worktree add

Config and hooks

git config extensions.worktreeConfig true
cd ../hotfix
git config --worktree core.sparseCheckout true

Config is shared by default: remotes, aliases, and hooks all come from the main .git. With extensions.worktreeConfig, git config --worktree writes the linked worktree's config.worktree, which is read after the shared config.

See: Configuration file

Sparse checkout

git worktree add --no-checkout -b sparse ../sparse main
cd ../sparse
git sparse-checkout set --cone src docs
git read-tree -mu HEAD

Patterns live in .git/worktrees/<id>/info/sparse-checkout, and set turns on extensions.worktreeConfig so core.sparseCheckout stays per worktree. read-tree fills the empty index.

See: git-sparse-checkout

Submodules

OperationSubmodule effect
removeneeds --force
moverefuses
multiple checkoutsexperimental, incomplete

Git still calls multiple checkouts experimental and warns that submodule support is incomplete. Avoid multiple checkouts of a superproject, and expect --force when removing one that carries submodules.

See: git worktree bugs

Workflows

Parallel branches

git worktree add ../feat -b feat main
git worktree add ../fix -b fix main

Each checkout has its own index, working files, and build directory, so a dirty feature tree never blocks a fix. Switch context by changing directory, not by stashing.

See: git worktree examples

Review a pull request

git fetch origin pull/123/head
git worktree add --detach ../review FETCH_HEAD

The fetch ref works on GitHub and other forges that expose pull/<n>/head. A detached worktree keeps the review off your branch list; remove it when the review lands.

See: Checking out pull requests locally

Hotfix while mid-feature

git worktree add -b hotfix ../hotfix main
cd ../hotfix && npm test

The hotfix builds and tests in its own directory while the feature checkout stays dirty. Commit on hotfix, then remove the worktree; the branch and commit remain.

See: git worktree examples

Bare repository hub

git clone --bare git@github.com:me/repo.git repo.git
git -C repo.git worktree add ../main main

A bare repository has no checkout of its own, so each checkout lives in a sibling directory while sharing one object store. This layout suits dotfiles and build hosts.

See: git clone --bare

One worktree per agent

git worktree add -b task-42 ../wt-42 origin/main
git worktree remove ../wt-42

Each agent gets an isolated index and working directory while objects and refs stay shared, so creating one is cheap. Name worktrees after the task or agent, and remove them when the run finishes. Avoid two agents on one branch.

See: git-worktree

Also see

0 Comments for this cheatsheet. Write yours!