What Is Git Worktree?

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:

1. A .git file (not a directory) inside every linked worktree. This file is a plain text pointer that contains a single line like gitdir: /path/to/main-repo/.git/worktrees/feature-x. It tells Git where the real repository data lives, so the linked worktree never duplicates the object store.
2. 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.

my-project/              # main worktree (branch: main)
├── .git/                # full Git repository
│   └── worktrees/
│       └── feature-x/   # per-worktree state for the linked worktree
│           ├── HEAD
│           ├── index
│           ├── commondir
│           └── gitdir
└── src/

../feature-x/            # linked worktree (branch: feature-x)
├── .git                 # file, not directory — contains:
│                        # gitdir: /path/to/my-project/.git/worktrees/feature-x
└── 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:

# Syntax: git worktree add <path> <branch>
git worktree add ../pr-review origin/fix/login-bug

Git creates the ../pr-review directory, checks out the fix/login-bug branch there, and sets up the .git pointer file. Your original working directory is completely untouched.

2. Work in the new worktree

cd ../pr-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

git worktree list

# Output:
# /home/user/my-project       abc1234 [main]
# /home/user/pr-review         def5678 [fix/login-bug]

4. Remove the worktree when you are done

# Go back to your main worktree
cd ../my-project

# Remove the linked worktree
git worktree remove ../pr-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.

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, list, and prune.
• 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.36 (April 2022): 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 it, and versions 2.17 and above provide the full set of management commands. To learn more about the broader git worktree ecosystem, head back to the home page.