git worktree add: Examples for New, Existing, and Remote Branches

git worktree add <path> creates a second working directory for the same repository and checks something out into it. With no other arguments it creates a branch named after the folder. Add -b for a new branch of your choosing, or name an existing branch to check that out instead.

git worktree add ../myrepo-auth -b feature/auth

The synopsis, from git worktree --help:

git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]
                 [-b <new-branch>] <path> [<commit-ish>]

Everything below is a variation on that one line.

The shorthand form

git worktree add ../hotfix

Creates the directory ../hotfix and a new branch called hotfix, based on your current HEAD. The branch name comes from the last path component. Convenient, and the reason people are sometimes surprised to find a branch they never asked for.

If a branch with that name already exists, git checks it out instead of creating one, unless it is already checked out in another worktree, in which case it refuses.

git worktree add with a new branch

Be explicit with -b:

git worktree add ../myrepo-auth -b feature/auth

Base it on something other than HEAD by naming a start point:

git worktree add ../myrepo-auth -b feature/auth main
git worktree add ../myrepo-auth -b feature/auth origin/main
git worktree add ../myrepo-auth -b feature/auth v2.1.0

-b refuses if the branch already exists. -B overrides that and resets the branch to the start point, which discards where the branch used to point. Reach for -B only when you mean it:

git worktree add ../myrepo-auth -B feature/auth main

git worktree add with an existing branch

Drop -b and pass the branch name as the second argument:

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

This is the review case: check out a colleague’s branch in its own folder, run it, test it, and leave your own working directory untouched.

One constraint, and it’s the one people hit most: a branch can only be checked out in one worktree at a time. Try it twice and git stops you:

Preparing worktree (checking out 'feature/auth')
fatal: 'feature/auth' is already checked out at '/Users/you/code/myrepo-auth'

The same rule blocks git switch feature/auth in your main repo while a worktree holds it. That is deliberate: two working copies moving one branch pointer would corrupt each other’s idea of where the branch is.

From a remote branch

If the branch does not exist locally but does exist on exactly one remote, git does the sensible thing automatically. This:

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

is treated as:

git worktree add --track -b feature/auth ../myrepo-pr origin/feature/auth

So a plain git worktree add ../pr-142 feature/from-a-teammate usually just works after a git fetch. Add --no-track if you don’t want upstream set.

Detached HEAD, for throwaway checkouts

git worktree add -d ../myrepo-poke
git worktree add --detach ../myrepo-v1 v1.0.0

No branch is created or claimed. Useful for bisecting, for building an old tag, or for letting an agent try something you fully intend to throw away. Commits made here belong to no branch, so create one before you get attached to the result.

The flags

Flag	What it does
`-b <branch>`	Create and check out a new branch
`-B <branch>`	Same, but reset the branch if it already exists
`-d`, `--detach`	Detached HEAD, no branch
`--track` / `--no-track`	Set or skip upstream when creating a branch
`--no-checkout`	Register the worktree without populating files, for sparse-checkout setup
`--lock --reason "<why>"`	Create it locked, so `prune` won’t reclaim it (removable media, network shares)
`-f`, `--force`	Override the safeguards below
`-q`, `--quiet`	Suppress the “Preparing worktree” chatter

Two errors you will meet

Branch already checked out. Covered above. Either work in the worktree that has it, or check out a different branch.

Path already registered. Delete a worktree folder with rm -rf and git still has it on the books. Reusing the path gives you:

fatal: '../x' is a missing but already registered worktree;
use 'add -f' to override, or 'prune' or 'remove' to clear

git worktree prune is the right answer. See removing a git worktree cleanly.

After you add one

A fresh worktree contains tracked files only. No node_modules, no .env, no .venv, no build output. Expect to do this every time:

cd ../myrepo-auth
npm install
cp ../myrepo/.env .

If a session in a new worktree reports a missing module or a missing key, this is almost always the reason.

Then check what you’ve got:

git worktree list

/Users/you/code/myrepo       eae19c2 [main]
/Users/you/code/myrepo-auth  eae19c2 [feature/auth]

Doing this per task

git worktree add plus install plus copy env plus start a session is four steps, and it repeats for every parallel task. Agents like Claude Code or Codex make that repetition frequent enough to notice, which is why Claude Code ships claude --worktree and why crystl folds worktree, branch, setup, and session into one action. See isolated sessions for the automated version, or keep running the commands above, which work anywhere git does.

git worktree add: Every Form of the Command