git worktree add: Complete Command Reference

The Basics: Three Forms You Actually Use

After years of watching developers learn git worktree, 95% of all usage comes down to three forms:

# Form 1: Check out an existing branch
git worktree add <path> <branch>

# Form 2: Create a new branch AND its worktree
git worktree add -b <new-branch> <path> <start-point>

# Form 3: Detached worktree at a specific commit/tag
git worktree add --detach <path> <commit-ish>

Everything else (--lock, --reason, --guess-remote, etc.) is a specialization of these. Let's walk through each.

Form 1: Existing Branch, New Folder

git worktree add ../myapp-hotfix hotfix/urgent

What happens:

  • Git creates ../myapp-hotfix/ as a new directory
  • Checks out the branch hotfix/urgent in it
  • Registers metadata in the main repo's .git/worktrees/myapp-hotfix/

Requirements:

  • The branch hotfix/urgent must exist (local or remote)
  • The branch cannot already be checked out in another worktree
  • The target path must not exist or must be empty

Error you'll hit if the branch is already checked out elsewhere:

fatal: 'hotfix/urgent' is already checked out at '/some/other/path'

The fix: either work in the existing worktree, or git worktree remove that one first.

Form 2: Create a New Branch in the Worktree

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

What happens:

  • Creates a new branch feat/search starting from origin/main
  • Checks it out in ../myapp-search/
  • The new branch now exists in your local repo

Why this is the most useful form: you almost always want a new branch for a new task — this does it in one shot.

Variants:

# Branch from current HEAD
git worktree add -b feat/search ../myapp-search

# Branch from a specific commit
git worktree add -b hotfix/patch ../myapp-patch abc1234

# Branch from a tag
git worktree add -b backport/1.2 ../myapp-1.2 v1.2.0

# Branch that tracks origin/main (uppercase -B overwrites existing)
git worktree add -B feat/search ../myapp-search origin/main

-b (lowercase) fails if the branch already exists. -B (uppercase) force-resets it. Use -b unless you have a reason not to.

Form 3: Detached Worktree

A worktree that's NOT attached to any branch — useful for inspecting history:

git worktree add --detach ../myapp-at-abc1234 abc1234

Use cases:

  • "What did the code look like at this commit?"
  • Bisecting without disturbing a branch
  • Building a specific release tag for testing
  • Running an old commit's test suite

You can still make commits in a detached worktree, but they won't belong to any branch until you run git switch -c new-branch.

The Useful Flags

--track

Sets up a new branch to track a remote branch:

git worktree add -b feat/auth --track origin/feat/auth ../myapp-auth

Now git push and git pull inside the worktree "just work" — no -u flag needed.

Shortcut: if you omit -b and provide a remote-only branch name, Git does this automatically (see --guess-remote).

--guess-remote

When you do:

git worktree add ../myapp-auth feat/auth

and feat/auth doesn't exist locally, but origin/feat/auth does — Git would normally fail. With --guess-remote (or configured via git config worktree.guessRemote true), Git creates a local feat/auth tracking origin/feat/auth for you.

git config --global worktree.guessRemote true   # enable permanently

Highly recommended — it eliminates an entire class of "why doesn't this work" errors.

--checkout / --no-checkout

By default add checks out files. --no-checkout creates the metadata without populating files — useful for very large repos when you need sparse checkout:

git worktree add --no-checkout ../myapp-big feat/big-feature
cd ../myapp-big
git sparse-checkout set src/feature-a   # only populate src/feature-a
git checkout

--lock and --reason

Locks the worktree immediately on creation, preventing accidental pruning:

git worktree add --lock --reason "CI build" /tmp/myapp-ci feat/big

Useful for worktrees on shared CI servers, removable drives, or mounted network filesystems.

--force

Allows creating a worktree at a path that already exists (overwrites) or on a branch already checked out elsewhere (violates the normal rule). Rarely safe. Use when you really know what you're doing.

git worktree add --force ../myapp-hotfix hotfix/urgent

--orphan

Creates a worktree on an orphan branch (no history). Useful for gh-pages or similar parallel-history setups:

git worktree add --orphan gh-pages ../myapp-docs

Requires Git 2.42+.

Full Syntax Reference

git worktree add [-f | --force]
                 [--detach]
                 [--checkout | --no-checkout]
                 [--lock [--reason <string>]]
                 [--orphan]
                 [-b <new-branch> | -B <new-branch>]
                 [--track]
                 [--guess-remote]
                 <path>
                 [<commit-ish>]
  • <path>: the directory to create (relative or absolute)
  • <commit-ish>: anything resolvable — branch name, tag, commit SHA, HEAD~5

Common Recipes

Recipe: Work on a teammate's branch

git fetch origin
git worktree add ../myapp-review alice/experimental

(Requires worktree.guessRemote = true or a pre-existing local branch.)

Recipe: Review a pull request locally

# Given PR #42 on GitHub
git fetch origin pull/42/head:pr-42
git worktree add ../myapp-pr-42 pr-42

Recipe: Hotfix without disturbing your feature

# Currently in ~/projects/myapp on branch feat/big-refactor with uncommitted changes
git worktree add ../myapp-hotfix -b hotfix/oncall origin/main
cd ../myapp-hotfix
# fix, commit, push
git push -u origin hotfix/oncall
cd ../myapp
# your feature branch is completely untouched

Recipe: Test a release tag

git worktree add ../myapp-v2.0 v2.0.0
cd ../myapp-v2.0
pnpm install && pnpm test
cd .. && git worktree remove ../myapp-v2.0

Recipe: Three parallel AI coding sessions

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

# Launch Claude Code in each:
cd ../myapp-auth    && claude &
cd ../myapp-search  && claude &
cd ../myapp-login   && claude &

Full guide: Claude Code + Git Worktree →

Common Errors and Fixes

fatal: 'feat/x' is already checked out at '/path'

A branch can only be in one worktree at a time. Fix: Use the existing worktree, or remove it first with git worktree remove.

fatal: 'path' already exists

The target directory exists and isn't empty. Fix: Pick a different path, or --force if you're sure (dangerous).

fatal: invalid reference: feat/x

The branch / ref doesn't exist, and --guess-remote isn't enabled. Fix: git fetch origin, then enable worktree.guessRemote, or explicitly use -b feat/x origin/feat/x.

fatal: HEAD is invalid

The repository's main HEAD is broken (rare, usually after aborted operations). Fix: git checkout main in the main repo, then retry.

Performance Notes

  • Creating a worktree is O(working-tree size) — files have to be checked out. For multi-GB repos, this takes seconds.
  • The .git/objects/ database is shared, so creating N worktrees does NOT multiply disk usage by N.
  • Worktrees share the reflog and stash of the main repo for metadata but each has its own HEAD and working state.

For huge monorepos, consider --no-checkout + sparse-checkout to only materialize the subset you need.

When to Use -b vs Checking Out First

There are two ways to get a new branch in a worktree. Both work. One is cleaner.

Clean:

git worktree add -b feat/x ../myapp-x origin/main

One command. New branch, correct starting point, worktree ready.

Messy:

git branch feat/x origin/main   # create branch first
git worktree add ../myapp-x feat/x   # then worktree it

Two commands. Same result. The first form is better: atomic, single rollback point if something goes wrong, less chance of the branch existing without its worktree.

Turn git worktree add into one click.

ParallelCode wires worktree creation directly to AI agents (Claude Code, Cursor Agent). Pick a branch, pick an agent, go — no commands, no ceremony.

Download ParallelCode — Free →