What Is Git Worktree and How to Use It

A git worktree is a feature that lets you check out multiple branches of the same repository simultaneously, each in its own directory on disk. Instead of stashing your work or committing half-finished changes to switch branches, you create a separate working tree linked to the same .git repository. Every worktree has its own working directory and index, but they all share the same Git history, refs, and object database. In short, a git worktree gives you parallel checkouts of different branches without cloning the repo again.

How Does Git Worktree Work?

When you run git worktree add, Git creates a new directory and checks out the specified branch into it. Internally, the mechanism relies on two key pieces:

A .git file (not a directory) inside every linked worktree. This file is a plain text pointer that contains a single line like gitdir: /home/you/code/acme/.git/worktrees/acme-hotfix. It tells Git where the real repository data lives, so the linked worktree never duplicates the object store.
A worktrees/ subdirectory inside the main repository’s .git directory. For each linked worktree, Git stores a small set of per-worktree state files here: HEAD, index, commondir, and lock files. The commondir file points back to the shared repository root so that all worktrees resolve refs, objects, and hooks from the same location.

Because every linked worktree shares the same object database, creating a new worktree is nearly instantaneous and uses very little extra disk space. Git also enforces that no two worktrees can have the same branch checked out at the same time, which prevents conflicting updates to branch refs.

Directory structure after adding a worktree

acme/                    # main worktree (branch: feature/payments)
|-- .git/                # full Git repository
|   +-- worktrees/
|       +-- acme-hotfix/ # per-worktree state for the linked worktree
|           |-- HEAD
|           |-- index
|           |-- commondir
|           +-- gitdir
+-- src/

../acme-hotfix/          # linked worktree (branch: hotfix/checkout-crash)
|-- .git                 # file, not directory — contains:
|                        # gitdir: /home/you/code/acme/.git/worktrees/acme-hotfix
+-- src/

Git Worktree Explained with Examples

The best way to understand what a git worktree is in practice is to walk through a real workflow. Suppose you are working on a feature branch and need to review a pull request on another branch without losing your place.

1. Create a linked worktree

From your main repository, add a new worktree for the branch you want to review:

Add a worktree for the review branch

# Syntax: git worktree add <path> <branch>
git fetch origin feature/auth-refactor
git worktree add -b feature/auth-refactor ../acme-review origin/feature/auth-refactor

Git creates the ../acme-review directory, checks out the feature/auth-refactor branch there, and sets up the .git pointer file. Your original working directory is completely untouched.

2. Work in the new worktree

Navigate and work normally

cd ../acme-review

# Run tests, read code, make review comments
npm test

# You can even make commits here
git add .
git commit -m "fix: address review feedback"

3. List all worktrees

See every worktree attached to the repo

git worktree list

# Output:
# /home/you/code/acme           d1e2f3a [feature/payments]
# /home/you/code/acme-review    b2c3d4e [feature/auth-refactor]

4. Remove the worktree when you are done

Clean up the linked worktree

# Go back to your main worktree
cd ../acme

# Remove the linked worktree
git worktree remove ../acme-review

For a deeper dive into every command and flag, see the full git worktree tutorial.

When Should You Use Git Worktree?

Git worktrees shine whenever context-switching between branches is expensive. Here are the most common use cases:

Code reviews: Check out a pull request branch in a separate directory while keeping your feature branch open. No stashing, no rebuilding.
Hotfixes: Create a worktree on main or a release branch to ship an urgent fix without disturbing your in-progress work.
Long-running builds or tests: Run your test suite in one worktree while continuing to code in another.
Comparing branches side by side: Open two worktrees in separate editor windows to visually diff implementations.
CI pipelines: Some CI setups use worktrees to test multiple branches in parallel without full clones.
Large monorepos: Cloning a multi-gigabyte repo twice is wasteful. A linked worktree reuses the object store and costs almost no additional disk space.

If you are deciding between worktrees and simply creating a new branch, the git worktree vs branch comparison breaks down exactly when each approach is the better choice.

How to Create a Git Worktree (Quick Start)

Getting started with git worktree takes just one command. Here is the fastest path from zero to a working setup:

Create your first worktree in 30 seconds

# You're on main, working on something. A hotfix comes in.
# Instead of stashing, create a worktree with a new branch:

git worktree add -b hotfix/login-crash ../hotfix main
cd ../hotfix

# Make the fix
# ... edit files ...
git commit -am "fix: prevent crash on expired session"
git push origin hotfix/login-crash

# Go back to your feature work — nothing changed
cd ../your-project

That is the core workflow. The git worktree add tutorial covers every flag and option in detail, including creating worktrees from remote branches, detached HEAD mode, and bare repositories.

Practical Git Worktree Examples

Beyond the basic walkthrough above, here are real-world scenarios where git worktree saves significant time:

Run Tests in One Worktree While Coding in Another

Parallel testing

# Create a worktree for running your test suite
git worktree add ../project-tests feature/new-api

# Terminal 1: run tests (slow CI suite)
cd ../project-tests && npm test

# Terminal 2: keep coding on your main checkout
cd ../your-project && code .

Review a PR Without Losing Your Place

PR review workflow

# Fetch and create a worktree for the PR branch
git fetch origin pull/42/head:pr-42
git worktree add ../pr-review pr-42

# Open in your editor, review, test
cd ../pr-review
npm install && npm test

# Done reviewing — clean up
cd ../your-project
git worktree remove ../pr-review

AI-Powered Parallel Development

AI coding tools like Claude Code and Cursor use worktrees to run multiple agents in parallel without file conflicts:

Multiple AI agents via worktrees

# Claude Code has built-in worktree support
claude --worktree feat/auth
claude --worktree fix/perf

# Each agent works in its own isolated directory

For more examples covering monorepo releases, team hotfix workflows, and CI pipelines, see our case studies.

Git Worktree History

The git worktree command was introduced in Git 2.5, released in July 2015. Before that, Git had an older, more limited mechanism called git-new-workdir, which was a contrib script that created symlinks into the .git directory. It was fragile and not officially supported.

The modern git worktree implementation replaced git-new-workdir with a first-class, safe alternative. Key milestones in its evolution include:

Git 2.5 (July 2015): Initial release with git worktree add and prune.
Git 2.7 (January 2016): Added git worktree list.
Git 2.17 (April 2018): Added git worktree move and git worktree remove, eliminating the need to manually delete directories and run prune.
Git 2.30 (December 2020): Introduced git worktree repair to fix broken links after moving worktrees or the main repository on disk.

Today, git worktreeis a stable, well-supported part of Git’s core toolkit. Any Git version 2.5 or later supports the basic commands, 2.17+ added move and remove, and 2.30+ added repair. To learn more about the broader git worktree ecosystem, head back to the home page.