git worktree add: Create a New Worktree

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 creates a new branch named after the last component of the path.

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

# Omit the branch — Git creates a new branch named "hotfix"
git worktree add ../hotfix

Create with a New Branch (-b flag)

Use -b to explicitly create a new branch and check it out in the worktree. This is the most common pattern for starting new feature work:

git worktree add -b feature/payment ../payment main

This command does three things in one step:

1. Creates a new branch called feature/payment pointing at the tip of main.
2. Creates a new working directory at ../payment.
3. Checks out the new branch in that directory.

Use -B (uppercase) instead to reset an existing branch to the start point:

# Reset feature/payment to the current tip of main
git worktree add -B feature/payment ../payment 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:

git worktree add ../bugfix-42 bugfix/issue-42

Remember that a branch can only be checked out in one worktree at a time. If bugfix/issue-42 is already checked out elsewhere, Git will refuse with an error. You would need to switch branches in the other worktree first.

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:

# Fetch latest refs from the remote
git fetch origin

# Create a worktree tracking the remote branch
git worktree add ../review origin/feature/review

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

git worktree add -b review-local ../review origin/feature/review

Common Options

Real-World Examples

Reviewing a pull request while keeping your work intact

# You're mid-feature on "feature/dashboard"
# A teammate asks you to review PR #87 on branch "feature/auth"

git worktree add ../pr-review feature/auth

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

# When done, clean up
cd ../main-repo
git worktree remove ../pr-review

Running tests on a stable branch while developing on another

# Create a worktree for the release branch
git worktree add ../release-v2 release/v2.0

# In one terminal, run the test suite against the release
cd ../release-v2 && npm test

# In another terminal, keep coding on your feature
cd ../main-repo && code .

Creating a detached worktree at a specific tag

# Check out the v1.5.0 tag in detached HEAD mode
git worktree add --detach ../v1.5-debug v1.5.0

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.

$ git worktree add ../fix 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):

$ git worktree add ../second main
fatal: 'main' is already checked out at '/path/to/repo'