git worktree add: Create a New Worktree

The git worktree add command creates a new working directory linked to your repository. The new worktree shares the same Git object database and refs as your main worktree, so there is no duplication of history. You can immediately start working on a different branch without stashing or committing in-progress work.

Try It: Mastering git worktree add

Two forms of add — existing branch and -b with remote — in the same acme scenario

The SetupYour Starting Point

You're deep in building a payment feature on the acme project. Half the code is written, tests are half-green, your editor has 12 tabs open. Today you'll learn three ways to use git worktree add — each solving a different real-world problem.

~/code/

1 directory

└── acme/ [feature/payments]← you are here
    ├── .git/  full git database
    ├── src/
    ├── package.json
    └── README.md

Basic Syntax

git worktree add <path> [<commit-ish>]

The path is the directory where the new worktree will be created. The optional commit-ish specifies which branch, tag, or commit to check out. If omitted, Git uses the last path component as the branch name: it creates that branch from HEAD if it does not exist yet, or checks out the existing branch if it is available.

Example: check out an existing branch

# Create a worktree at ../acme-hotfix, checking out the "main" branch
git worktree add ../acme-hotfix main

Example: infer the branch name from the path

# Omit the branch — Git uses "acme-hotfix" as the branch name
# If it doesn't exist, Git creates it from HEAD
git worktree add ../acme-hotfix

Create with a New Branch (-b flag)

The -b flag creates a new branch and checks it out in the new worktree in a single command. This is the most common pattern for starting new feature or hotfix work. Its full syntax is:

git worktree add -b <new-branch> <path> [<start-point>]

<new-branch> — the name of the branch to create (must not already exist).
<path> — the directory where the new worktree will live.
[<start-point>] — the commit, branch, or tag the new branch will point to. If omitted, defaults to HEAD (your current commit).

Example — create a hotfix branch from main:

One command does three things

git worktree add -b hotfix/checkout-crash ../acme-hotfix main

This single command:

Creates a new branch hotfix/checkout-crash pointing at the tip of main.
Creates a new working directory at ../acme-hotfix.
Checks out the new branch in that directory.

Without -b, you would need two separate steps to achieve the same result:

Comparison: two steps vs one

# Equivalent two-step approach (without -b)
git worktree add ../acme-hotfix main
cd ../acme-hotfix && git checkout -b hotfix/checkout-crash

If the branch name you pass to -b already exists, Git will refuse with an error:

Error: branch already exists

$ git worktree add -b hotfix/checkout-crash ../acme-hotfix main
fatal: a branch named 'hotfix/checkout-crash' already exists

Force-reset a Branch (-B flag)

The -B flag (uppercase) works like -b, but with one key difference: if the branch already exists, it force-resets it to the given start point instead of failing. If the branch does not exist, it creates it — exactly like -b.

git worktree add -B <branch> <path> [<start-point>]

Example — reset an existing hotfix branch back to the tip of main:

Force-reset with -B

# hotfix/checkout-crash already exists but has diverged
# -B resets it to point at the current tip of main
git worktree add -B hotfix/checkout-crash ../acme-hotfix main

Warning: -B discards any commits on the existing branch that are not in the start-point. Use it only when you intentionally want to throw away the old branch state and start fresh.

A common use case: your previous hotfix attempt went wrong, and you want to start over from a clean main.

Create from an Existing Branch

If the branch already exists locally, pass it as the second argument. Git will check it out in the new worktree:

Check out an existing local branch

git worktree add ../acme-hotfix main

Remember that, by default, a branch can only be checked out in one worktree at a time. If main is already checked out elsewhere, Git will refuse with an error unless you explicitly override the safeguard with --force. In normal workflows, switching branches in the other worktree is safer.

Create from a Remote Branch

To work on a branch that exists on a remote but not locally, fetch first and then create the worktree. Git will automatically set up tracking if there is a matching remote branch:

Track a remote branch

# Fetch latest refs from the remote
git fetch origin feature/auth-refactor

# Create a worktree with a local tracking branch
git worktree add -b feature/auth-refactor ../acme-review origin/feature/auth-refactor

If you want a local branch name that differs from the remote, combine -b with the remote ref:

git worktree add -b auth-review ../acme-review origin/feature/auth-refactor

Common Options

Flag	Description
-b <branch>	Create a new branch at the given start-point (or HEAD) and check it out in the worktree. Fails if the branch already exists.
-B <branch>	Like -b, but if the branch already exists, force-reset it to the start-point. Discards any commits on the old branch that are not reachable from the start-point.
-d, --detach	Check out the commit in detached HEAD state instead of creating or switching to a branch.
--lock	Lock the worktree immediately after creation to prevent pruning.
-f, --force	Allow adding a worktree even if the branch is checked out in another worktree (creates a second checkout — use with caution).
--reason <string>	Set a reason string when used with --lock (Git 2.33+).
-q, --quiet	Suppress feedback messages.

Real-World Examples

Emergency hotfix while mid-feature

Hotfix workflow

# You're deep in feature/payments on the acme project
# Production checkout page is broken — need a hotfix NOW

git worktree add ../acme-hotfix main
cd ../acme-hotfix
git checkout -b hotfix/checkout-crash

# Fix the bug, commit, push
git add src/checkout.ts
git commit -m "fix: null check on cart total"
git push origin hotfix/checkout-crash

# Back to your feature — zero context lost
cd ../acme

Reviewing a teammate's PR from a remote branch

PR review workflow

# A teammate asks you to review their auth refactor PR
# The branch only exists on the remote

git fetch origin feature/auth-refactor
git worktree add -b feature/auth-refactor ../acme-review origin/feature/auth-refactor

cd ../acme-review
# Run tests, inspect code, leave review comments

# When done, clean up
cd ../acme
git worktree remove ../acme-review

Debugging a specific release tag

Detached HEAD worktree

# Check out the v2.3.1 tag in detached HEAD mode
git worktree add --detach ../acme-debug v2.3.1

Common Errors

"invalid reference"

This error occurs when the branch or commit you specified does not exist. Double-check spelling, or run git fetch to pull down remote refs. See the full troubleshooting guide at Troubleshooting: invalid reference.

Error output

$ git worktree add ../acme-hotfix bad-branch-name
fatal: invalid reference: bad-branch-name

"already checked out"

Git prevents a branch from being checked out in two worktrees at once. Either switch branches in the existing worktree, or use --force (not recommended for normal workflows):