---
topic: worktrees
source_keys:
  - git-scm-worktree-docs
---

## Full `add` flag table

| Flag | Meaning |
|---|---|
| `-b <branch>` | Create and check out a new branch; fails if it exists |
| `-B <branch>` | Like `-b` but resets the branch if it already exists |
| `-d` / `--detach` | Detach HEAD; useful for throwaway experiments |
| `--orphan` | Create empty unborn branch |
| `--no-checkout` | Suppress initial checkout (for sparse-checkout setup) |
| `--guess-remote` | Look for a matching remote-tracking branch by path basename |
| `--lock [--reason <str>]` | Lock immediately on creation (atomic; avoids race vs. add-then-lock) |
| `-f` / `--force` | Allow when branch is already checked out elsewhere |
| `--relative-paths` | Link via relative paths (portable across moves) |

Using `-` as `<commit-ish>` is shorthand for `@{-1}` (the branch checked out before the current one), e.g. `git worktree add <path> -`.

## New unborn branch

```bash
git worktree add --orphan -b <branch> <path>
```
Creates an empty branch with no commits.

## Sparse-checkout worktree

Suppress the initial checkout to configure sparse-checkout first:
```bash
git worktree add --no-checkout ../sparse main
cd ../sparse
git sparse-checkout init --cone
git sparse-checkout set src/
git checkout main
```

## Worktree on removable media

```bash
git worktree add --lock --reason "external SSD" <path> <branch>
git worktree unlock <path>  # when reconnected
```

## Remote-branch disambiguation

```bash
git worktree add <path> <remote>/<branch>
```
For ambiguous names across remotes, `checkout.defaultRemote` config disambiguates explicitly, or `--guess-remote` auto-matches by path basename (default controlled by `worktree.guessRemote` config). If a branch name matches multiple remotes during `worktree add` and neither is set, Git refuses rather than guessing.

## Configuration

| Key | Effect |
|---|---|
| `worktree.guessRemote` | Default for `--guess-remote` on `git worktree add` |
| `worktree.useRelativePaths` | Default for `--relative-paths` on `git worktree add` (link via relative paths — portable across moves) |
| `gc.worktreePruneExpire` | How long before stale worktree metadata is pruned by `git gc` |
| `extensions.worktreeConfig` | Enable per-worktree config scope (`config.worktree` file) — see Gotchas in SKILL.md |
| `checkout.defaultRemote` | Disambiguates which remote to use when a branch name matches multiple remotes during `worktree add` |