git worktree add: new branch, existing branch, remote branch or detached

git worktree add <path> -b <new-branch> creates a new folder and a new branch, and checks the branch out in that folder. git worktree add <path> <branch> checks out a branch that already exists. git worktree add --detach <path> <commit> gives you a folder at a commit with no branch at all. Below is each form with the output Git really prints, the two errors you’ll meet, and where to put the folder.

If you’re new to worktrees, start with how to use git worktree; if you’re setting them up for AI agents, with git worktrees for Claude Code and Codex. This page is the reference for the one command.

A new branch: -b

The form I use most. The branch starts at your current HEAD:

$ git worktree add ../app-feature-search -b feature/search
Preparing worktree (new branch 'feature/search')
HEAD is now at 85f04f1 Add readme line

To start it somewhere else, put a commit, tag or branch at the end:

$ git worktree add ../app-hotfix -b hotfix/login v2.3.0
Preparing worktree (new branch 'hotfix/login')
HEAD is now at 774398e Initial commit

-b refuses if the branch already exists. -B resets an existing branch to the start point instead, but it still can’t touch a branch that’s checked out somewhere:

$ git worktree add -B feature/search ../app-x
fatal: 'feature/search' is already used by worktree at '~/code/app-feature-search'

An existing branch

Leave out -b and name the branch:

$ git worktree add ../app-fix-login fix-login
Preparing worktree (checking out 'fix-login')
HEAD is now at 85f04f1 Add readme line

The rule that catches everyone: a branch can be checked out in only one worktree at a time. Your main folder counts, so this fails while you’re on main:

$ git worktree add ../app-main main
Preparing worktree (checking out 'main')
fatal: 'main' is already used by worktree at '~/code/app'

If you only wanted to work on that branch, go to the folder that has it: switching between git worktrees is cd, not a Git command. Otherwise create a new branch from it, or use --detach below:

$ git worktree add ../app-review -b review/main main
Preparing worktree (new branch 'review/main')
HEAD is now at 85f04f1 Add readme line

A branch that only exists on the remote

If the branch isn’t local but exactly one remote has it, Git creates a local branch that tracks the remote one (git-worktree docs):

$ git worktree add ../app-feature-x feature-x
Preparing worktree (new branch 'feature-x')
branch 'feature-x' set up to track 'origin/feature-x'.
HEAD is now at 85f04f1 Add readme line

Fetch first, or Git won’t know the branch exists. To give the local branch a different name, say it with -b and --track:

$ git worktree add ../app-track -b feature/remote-x --track origin/feature-x
Preparing worktree (new branch 'feature/remote-x')
branch 'feature/remote-x' set up to track 'origin/feature-x'.
HEAD is now at 85f04f1 Add readme line

No branch at all: --detach

For looking at an old commit, running a build at a tag, or bisecting without disturbing your work:

$ git worktree add --detach ../app-v1 HEAD~1
Preparing worktree (detached HEAD 774398e)
HEAD is now at 774398e Initial commit

The Codex desktop app starts its own worktrees this way, in a detached HEAD, so it can make several without adding branches (Codex worktrees).

Only a path: the branch you didn’t ask for

With just a path, Git creates a branch named after the folder:

$ git worktree add ../app-quick
Preparing worktree (new branch 'app-quick')
HEAD is now at 85f04f1 Add readme line

That’s documented behavior, and it’s how a repository fills up with branches called app-quick. I always pass -b with a real name.

Check what you made

Here’s my scratch repository after the new-branch, existing-branch, detached and path-only examples:

$ git worktree list
~/code/app                 85f04f1 [main]
~/code/app-feature-search  85f04f1 [feature/search]
~/code/app-fix-login       85f04f1 [fix-login]
~/code/app-quick           85f04f1 [app-quick]
~/code/app-v1              774398e (detached HEAD)

git branch -vv marks the branches checked out in another worktree with a + and the folder:

$ git branch -vv
+ app-quick      85f04f1 (~/code/app-quick) Add readme line
+ feature/search 85f04f1 (~/code/app-feature-search) Add readme line
+ fix-login      85f04f1 (~/code/app-fix-login) Add readme line
* main           85f04f1 Add readme line

For scripts, git worktree list --porcelain prints one field per line (worktree, HEAD, branch or detached).

Where to put the folder

Three conventions, all fine:

• Next to the repository: ../app-<task>. Out of the way of your editor’s search and your build tools. This is what the examples above use.
• Inside it: .worktrees/<task>. Everything for one project in one place, but add .worktrees/ to .gitignore first, or the folder shows up in git status as untracked.
• Wherever your tool puts it: Claude Code uses .claude/worktrees/<name> on a branch called worktree-<name> (Claude Code docs); the Codex desktop app uses $CODEX_HOME/worktrees.

Name the folder and the branch after the task. Six months later, git worktree list should still tell you what each one was for.

What the new folder doesn’t have

Only tracked files are checked out. node_modules, build output, .env and anything else in .gitignore stay in the folder where they were created. Run your install and copy your config before you start work there. The worktrees guide covers what to do about each.

When you’re done with a worktree, removing it has its own traps: see git worktree remove, prune and lock.