Glossary

Git Worktrees

Git worktrees let you keep several working directories for one repository side by side. An unfinished feature can stay exactly as it is while you prepare an urgent hotfix on another branch in a separate directory.

Short definition

Multiple checkouts backed by one shared repository.

Git uses the git worktree command and model to manage multiple working trees attached to a single repository. A normal git clone or git init creates the main working tree; additional directories created with git worktree add are called linked worktrees. “Main” describes the working tree’s role, not a requirement to have the main branch checked out there.

A worktree is neither a new branch nor a new clone. It is a particular working directory with checked-out files and worktree-specific state such as HEAD and the index. All worktrees share the same history, most refs, and the Git object database that stores commits, trees, and other objects.

The problem it solves

Switch context without stashing unfinished work.

A working tree can have only one state checked out at a time. Switching branches is awkward when it contains uncommitted changes or a running development server. A linked worktree provides another directory and a separate index without cloning the complete history again.

prepare an urgent fix from the main branch alongside an unfinished feature
run two application versions at the same time to compare their behaviour
review someone else’s branch without switching or cleaning the current working copy
use a separate directory for a release or bug reproduction
work on different branches in parallel while sharing the same history

Practical example

Fixing a payment webhook beside an unfinished checkout feature.

A developer is working on feature/new-checkout in the main worktree and does not want to commit or stash the unfinished files. They create hotfix/payment-webhook from the current tip of the main branch and check it out at the same time in the neighbouring ../shop-hotfix directory.

In the new directory, they fix the webhook, run the tests, create a commit, and send the branch for review. The git worktree list command shows each working tree’s path, commit, and branch. When the work is complete, they first confirm that the directory is clean and then remove the linked worktree with the appropriate Git command; this does not delete the hotfix branch or its commits from the repository.

Shell

git worktree add -b hotfix/payment-webhook ../shop-hotfix main
git -C ../shop-hotfix status

# In ../shop-hotfix, edit, test, commit, and push the fix.
git worktree list
git -C ../shop-hotfix status --short

How it works

One repository store → main worktree (feature) + linked worktree (hotfix).

The diagram shows a shared Git repository store and separate working directories. The worktrees share the object database and ordinary branch refs, but each has its own checkout, HEAD, index, and uncommitted files.

Shared repository The object database stores commits, trees, and blobs for every worktree. A commit created in one worktree is therefore known to the others.
Main worktree The original working tree has its own HEAD, index, and files. In this example it remains on feature/new-checkout with the unfinished change intact.
Linked hotfix worktree The second directory has its own HEAD, index, and checkout of the hotfix/payment-webhook branch.
Independent file changes Editing or staging files in the hotfix directory does not overwrite the unfinished files or index in the feature directory.
Controlled cleanup git worktree remove checks the state and removes both the linked worktree and its administrative record. Prune is for orphaned metadata left by a missing directory, not the routine replacement for remove.

Key concepts

Working directories stay separate while history remains shared.

Using worktrees well depends on distinguishing a repository, a working tree, and a branch. Each has a different lifecycle.

Main and linked worktrees

A non-bare repository has one main worktree and may have additional linked worktrees. A linked worktree contains a small .git file pointing to administrative data in the shared Git directory; it does not contain a second complete .git database.

A separate HEAD and index

Each working tree tracks its own checkout and staging area. You can therefore prepare a feature in one directory and a hotfix in another without mixing their uncommitted files or staged changes.

Shared objects and refs

Commits, trees, and blobs live in the shared object database. Ordinary local branches are shared refs too, so moving a branch in one working tree is visible across the repository. Some pseudo-refs, particularly HEAD, are worktree-specific instead.

Adding and listing worktrees

git worktree add <path> <branch> checks out an existing branch; the -b <new-branch> form creates one from the specified commit. git worktree list shows the working trees and their revisions.

Move, remove, prune, and repair

Use git worktree move for a normal relocation. Remove is the standard way to clean up a finished linked worktree and, unless forced, refuses a dirty directory. Prune removes orphaned administrative data after directories have already disappeared; git worktree prune --dry-run can preview the result. Repair fixes stale administrative links after the main or a linked worktree was moved outside Git.

One branch, one checkout

By default, Git refuses to add a worktree for a local branch that is already checked out elsewhere. This safeguard prevents two directories from moving the same branch without coordination; bypassing it with force is not a normal workflow.

Benefits, limitations, and common mistakes

Fast parallel environments still depend on one repository.

Benefits

the unfinished directory remains untouched while another branch is fixed
shared objects usually save disk space and avoid fetching the history again compared with a separate clone
each worktree has its own index, uncommitted changes, and checkout
git worktree list provides one overview of paths and branches

Limitations and common mistakes

a worktree is not a backup because it depends on the repository’s shared history and administrative data
deleting the directory manually can leave metadata behind; git worktree remove is the proper procedure
the same local branch cannot normally be checked out in several worktrees at once
shared repository configuration or hooks can affect every worktree
submodules and some IDEs, development servers, or scripts may have their own limitations with multiple checkouts

Practical use and comparison

A worktree, branch, clone, and repository are not interchangeable.

A branch is a named reference to a commit. A worktree is a directory in which a branch or particular commit is checked out. Creating a linked worktree can create a new branch at the same time, but the two serve different purposes and can be managed separately.

A repository contains history and Git metadata; a working tree is where its contents are edited. A linked worktree is therefore not a second Git repository. It shares the object database, refs, and normally the repository configuration, while keeping its own HEAD, index, and working files.

A separate git clone typically has its own Git directory, object database, configuration, and remote-ref state. It offers stronger operational isolation and can be moved or deleted independently, but takes more space and needs its own fetch. Worktrees are leaner and more convenient for branches of one local repository; they are not automatically the better option for every automation or isolated environment.

Pull requests and CI do not change when worktrees are used. A worktree only organises local working directories. Reviews, remote branches, permissions, and automated checks remain the responsibility of the hosting service and CI/CD.

A safe workflow

Check the state before removal and clean up through Git.

Worktrees make context switching easier, but they do not protect uncommitted files or resolve conflicts between local environments.

verify the starting commit and choose an explicit new branch name before adding a worktree
review the overview with git worktree list and inspect a specific directory with git -C <path> status
plan for collisions between ports, container names, local databases, .env files, and build outputs
remove a linked worktree only after committing or deliberately preserving any work you need
if the directory was removed manually, inspect git worktree prune --dry-run before cleaning up the orphaned metadata
publish important commits to a remote repository; a worktree by itself is not a backup

Common questions

Git Worktrees without common misconceptions.

Is a linked worktree a new Git repository?

No. It is another working directory attached to the same repository. It shares the repository’s objects, ordinary refs, and most configuration, but has its own HEAD, index, and checked-out files.

Is a worktree the same as a branch?

No. A branch is a reference to a commit; a worktree is a working directory with a checkout. Git may create a new branch when adding a worktree, but the two concepts remain separate.

Can the same branch be checked out in multiple worktrees?

Git rejects this in a normal workflow because two working directories could move the same branch. Give each worktree its own branch, or use a detached HEAD for temporary inspection and testing.

What does git worktree remove do?

It removes a linked working tree and its administrative record. Without force, it refuses a worktree with modified or untracked files; it does not delete the branch or its commits.

When should I use git worktree prune?

Use it when a working directory is already missing and the repository still holds orphaned metadata for it. Use remove for normal cleanup, and preview a prune safely with --dry-run.

Hands-on experience

I use multiple working trees to keep changes separate and verifiable.

In PHP applications, I combine Git workflows with tests and review so an unfinished feature never blocks an urgent fix or a check of another branch.

View my expertise Discuss your project

Official git worktree documentation