Git Worktree - The Complete Guide (2026)

What Is a Git Worktree?

A git worktree is a linked working directory attached to a single Git repository, allowing you to check out multiple branches simultaneously from the same repo without cloning it again.

In traditional Git usage, one repository equals one working directory. You can only have one branch checked out at a time. Switching branches means stashing or committing your current work, running git checkout, and waiting for your editor, file watchers, and build tools to re-index everything. The git worktree command removes that constraint.

With worktrees, a single .git directory can back any number of working trees, each on a different branch, each in its own folder on disk. They share the same object database, so they are lightweight — no duplicated commits, no duplicated blobs.

# One repo, three branches checked out at once
~/projects/myapp              # main branch
~/projects/myapp-feature-auth # feat/auth branch (a worktree)
~/projects/myapp-bugfix-123   # fix/123 branch (a worktree)

This is the feature that unlocks true parallel development — and it is what makes modern AI-assisted coding workflows like ParallelCode practical at scale.

What You'll Learn in This Guide

  • ✅ What git worktree is and how it differs from cloning
  • ✅ How the underlying .git/worktrees/ mechanism works
  • ✅ Every git worktree subcommand explained with examples
  • ✅ Common pitfalls and how to avoid them
  • ✅ Real-world workflows (hotfixes, code review, parallel AI agents)
  • ✅ When to use worktrees — and when not to

Reading time: ~18 minutes Level: Beginner → Intermediate

Why Git Worktree Exists

Before git worktree landed in Git 2.5 (July 2015), developers had three unsatisfying options when they needed to work on multiple branches:

  1. Stash and switch — lose context, waste editor re-indexing time
  2. Clone the repo twice — duplicate every object on disk, manage two remotes
  3. Keep multiple repos with different remotes — clunky, error-prone

None of these scaled. Worktrees solved the core problem: letting Git handle multiple checkouts of the same repository from a single object store.

The Mental Model

Think of your Git repository as having two layers:

  • Object database (.git/objects/) — all commits, trees, blobs. This is the "source of truth."
  • Working tree — the files you see on disk, which reflect one specific commit.

Traditional Git ties one object database to one working tree. Worktrees break that 1:1 relationship: one object database, many working trees. Each worktree points to a different HEAD, but they all share the same underlying storage.

How to Use Git Worktree: The Essential Commands

1. Create a Worktree

The most common operation. Pick a branch, pick a directory, go:

# Check out an existing branch in a new folder
git worktree add ../myapp-hotfix hotfix/critical

# Create a new branch AND its worktree in one command
git worktree add -b feat/payments ../myapp-payments main

# Worktree based on a tag, commit, or remote ref
git worktree add ../myapp-v1.2 v1.2.0
git worktree add ../myapp-pr-42 origin/pr/42

After running this, cd ../myapp-hotfix gives you a fully functional Git checkout. You can commit, pull, push, rebase — everything a normal clone can do.

For a deep-dive on every flag, edge case, and failure mode, see git worktree add: Complete Command Reference →

2. List Worktrees

git worktree list
# Output:
# /home/user/myapp             abc1234 [main]
# /home/user/myapp-hotfix      def5678 [hotfix/critical]
# /home/user/myapp-payments    9876abc [feat/payments]

Add --porcelain for machine-readable output (great for scripts).

3. Remove a Worktree

# Clean removal (only if worktree has no uncommitted changes)
git worktree remove ../myapp-hotfix

# Force removal (discards uncommitted changes in that worktree)
git worktree remove --force ../myapp-hotfix

If a worktree's directory was deleted manually or became inaccessible, clean up the stale reference:

git worktree prune

Removing worktrees correctly is where most users trip up. Full guide: How to Remove a Git Worktree (Without Breaking Your Repo) →

4. Move a Worktree

git worktree move ../myapp-hotfix ../archive/myapp-hotfix

Never move a worktree folder with mv — Git stores absolute paths internally and will lose track of it.

5. Lock and Unlock

Useful when a worktree lives on removable media or a network mount:

git worktree lock ../myapp-on-usb --reason "USB drive not always connected"
git worktree unlock ../myapp-on-usb

A locked worktree cannot be pruned or moved until unlocked.

6. Repair

If you move the main repository or a worktree folder manually, run:

git worktree repair

This fixes the two-way pointers between the main repo and its worktrees.

Under the Hood: Where Does the Data Live?

Understanding the file layout helps you debug weird situations.

~/myapp/
  .git/
    worktrees/
      myapp-hotfix/        # metadata for this linked worktree
        HEAD
        commondir
        gitdir
        locked             # exists if locked
    ...
  src/
  package.json

~/myapp-hotfix/
  .git                     # NOT a folder — a text file pointing to main .git/worktrees/myapp-hotfix
  src/
  package.json

Key observations:

  • The main repository owns the object database (.git/objects/)
  • Each linked worktree has a small metadata folder under .git/worktrees/<name>/
  • Inside the linked worktree, .git is a plain text file, not a directory — it redirects Git to the main repo
  • All objects (commits, blobs, trees) are shared — a 2 GB repo with 5 worktrees still uses ~2 GB, not 10 GB

This design is what makes worktrees cheap — creating one is essentially free disk-wise.

Why Git Worktree Matters for AI Coding

Worktrees became an obscure power-user feature for a decade. Then AI coding assistants made them essential overnight.

Modern AI tools — Claude Code, Cursor Agent, Codex, Aider — can now complete real tasks autonomously, each taking minutes. If you run them one at a time on the same working directory, you're bottlenecked on a single branch, waiting for each task to finish.

Run them in separate worktrees, and suddenly:

  • ✅ Three AI agents work on three features in parallel
  • ✅ Each has its own isolated branch — no file collisions
  • ✅ You can run tests / dev servers in each worktree independently
  • ✅ Merge winners, delete losers, move on

This is the core insight behind ParallelCode: one-click worktree creation wired directly to AI agents. But even without a UI, the raw git worktree command is the enabling primitive.

Practical setup guide: Using Claude Code with Git Worktree: Step-by-Step →

Common Pitfalls (and Fixes)

"fatal: 'branch' is already checked out at '...'"

Each branch can only be checked out in one worktree at a time. If you try to git checkout or git worktree add a branch that's already in another worktree, Git refuses.

Fix: Either work in the existing worktree, or remove it first.

"cannot delete branch 'foo' checked out at '...'"

You're trying to git branch -d foo while a worktree has it checked out. Git protects you from orphaning a worktree's HEAD.

Fix: Remove the worktree first, then delete the branch. Full walkthrough: Fix: Cannot Delete Branch Used by Worktree →

Worktree folder manually deleted

You rm -rf'd a worktree folder. Git still thinks it exists.

Fix: git worktree prune removes the dangling metadata.

Hooks don't run / run twice

Git hooks live in .git/hooks/ on the main repository. Linked worktrees share the same hooks directory by default. If a hook does something path-dependent (like "run tests in project root"), make sure it resolves paths relative to the worktree, not the main repo:

# In a hook:
WORKTREE_ROOT="$(git rev-parse --show-toplevel)"
cd "$WORKTREE_ROOT"

Node/Python dependencies duplicated

Each worktree is a separate directory, so node_modules/ or .venv/ are not shared. This is by design — different branches may have different dependencies. If you want to share, use a tool-specific solution (pnpm's content-addressable store, uv's shared cache).

Real-World Workflows

Workflow 1: The Emergency Hotfix

You're deep into a feature when a production bug lands. Without worktrees: stash, switch, lose editor state.

# With worktrees — takes 5 seconds:
git worktree add ../myapp-hotfix -b hotfix/urgent origin/main
cd ../myapp-hotfix
# fix, test, commit, push — feature branch untouched
git push origin hotfix/urgent
cd ../myapp          # back to your feature, zero context loss

Workflow 2: Reviewing a Pull Request Locally

Need to actually run the reviewer's code? Don't pollute your main working tree:

git fetch origin pull/42/head:pr-42
git worktree add ../myapp-pr-42 pr-42
cd ../myapp-pr-42
pnpm install && pnpm test
# done? clean up:
cd .. && git worktree remove myapp-pr-42
git branch -D pr-42

Workflow 3: Parallel AI Agents

Spin up three worktrees, launch Claude Code in each, let them work in parallel:

git worktree add ../myapp-auth    -b feat/auth    origin/main
git worktree add ../myapp-search  -b feat/search  origin/main
git worktree add ../myapp-billing -b feat/billing origin/main

# In three terminal tabs:
cd ../myapp-auth    && claude
cd ../myapp-search  && claude
cd ../myapp-billing && claude

Three agents, three branches, zero conflicts. Merge the ones that land well.

For a full walkthrough with ParallelCode's one-click UI: Claude Code + Git Worktree →

When NOT to Use Worktrees

Worktrees are the right tool for short-lived, parallel branches. They're not the right tool for:

  • Long-running separate projects — use separate repos
  • Experiments you'll abandon — a quick git stash is faster
  • Cross-team collaboration — worktrees are local-only; your teammates don't see them
  • Branches with wildly different dependency trees where you rarely switch between them

If you find yourself with >10 worktrees that you never clean up, you're probably over-using the feature.

FAQ: Quick Answers

Q: How many worktrees can I have? A: No hard limit. Practically, 3-10 is the sweet spot. Performance-wise, worktrees are cheap — the limit is your cognitive load.

Q: Do worktrees share the .gitignore? A: Yes — it's tracked in Git, so every worktree sees the same rules for its branch's version of the file.

Q: Can I have a worktree on a detached HEAD? A: Yes. git worktree add --detach ../inspect abc1234 creates one at a specific commit with no branch.

Q: Do worktrees work with Git LFS? A: Yes, but LFS caches per-repo, so each worktree pulls LFS content into its own .git/lfs/ if configured independently. Most setups share via the main repo's LFS cache.

Q: Can I push from a worktree? A: Yes — pushing, pulling, fetching, rebasing, merging all work normally in a worktree.

Q: Is git worktree available in older Git versions? A: Requires Git 2.5+ (2015). git worktree move / remove / repair need 2.17+. Use git --version to check.

Summary: The Core Commands at a Glance

git worktree add <path> <branch>        # create
git worktree add -b <new> <path> <ref>  # create with new branch
git worktree list                       # list all
git worktree remove <path>              # remove clean
git worktree remove --force <path>      # remove with uncommitted changes
git worktree move <from> <to>           # rename/move
git worktree lock <path>                # prevent pruning
git worktree unlock <path>              # release lock
git worktree prune                      # clean up deleted worktrees
git worktree repair                     # fix broken pointers

Keep Going

Now that you understand the fundamentals, go deeper:

Stop managing worktrees by hand

ParallelCode turns every git worktree add into a single click, wired to Claude Code, Cursor Agent, and more. Run 3+ AI agents in parallel without touching the terminal.

Download ParallelCode — Free →

Related posts