# git worktree add: Usage, Options & Common CI Errors

> git worktree add checks out an extra working tree from the same repo. Reference for -b, --detach, --track, and the already-checked-out and path-exists errors.

Source: https://latchkey.dev/learn/command-reference/git-worktree-add  
Updated: 2026-06-25

git worktree add gives you a second working directory backed by the same repository.

Worktrees let a pipeline build several branches in parallel without re-cloning. Each tree has its own checkout but shares the object store, saving time and disk.

## What it does

git worktree add creates a new working directory linked to the current repository, checking out a branch or commit there. The new tree shares objects and refs with the main one.

## Common usage

```Terminal
git worktree add ../feature feature
git worktree add -b hotfix ../hotfix main
git worktree add --detach ../inspect <sha>
git worktree add --track -b local ../local origin/remote
```

## Options

| Flag | What it does |
| --- | --- |
| <path> [<branch>] | Create a worktree at path on a branch |
| -b <name> | Create a new branch for the worktree |
| --detach | Check out a commit in detached HEAD |
| --track | Set up upstream tracking |
| -f / --force | Allow an already-checked-out branch |

## Common errors in CI

fatal: '<branch>' is already checked out at '<path>' - a branch can be checked out in only one worktree at a time; use a different branch or --force. fatal: '<path>' already exists means the target directory is non-empty; pick a clean path.

## Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git worktree add: Usage, Options & Common CI Errors?

Worktrees let a pipeline build several branches in parallel without re-cloning. Each tree has its own checkout but shares the object store, saving time and disk.

### What it does?

git worktree add creates a new working directory linked to the current repository, checking out a branch or commit there. The new tree shares objects and refs with the main one.

### Common errors in CI?

fatal: '<branch>' is already checked out at '<path>' - a branch can be checked out in only one worktree at a time; use a different branch or --force. fatal: '<path>' already exists means the target directory is non-empty; pick a clean path.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt