# git worktree: Usage, Options & Common CI Errors

> git worktree checks out multiple branches into separate directories from one repo. Reference for add, list, remove, prune, and locked-branch errors.

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

git worktree lets one repository have several working directories, each on a different branch.

Worktrees avoid re-cloning when you need two branches checked out at once - handy for parallel CI builds.

## What it does

git worktree creates additional working trees linked to the same repository, so you can have multiple branches checked out simultaneously without separate clones.

## Common usage

```Terminal
git worktree add ../hotfix hotfix
git worktree add -b release ../release origin/release
git worktree list
git worktree remove ../hotfix
git worktree prune
```

## Options

| Subcommand | What it does |
| --- | --- |
| add <path> [<branch>] | Create a worktree at path |
| add -b <new> <path> <ref> | Create a branch in a new worktree |
| list | List all worktrees |
| remove <path> | Delete a worktree |
| prune | Clean up stale worktree metadata |

## Common errors in CI

fatal: 'X' is already checked out at '…' - a branch can be checked out in only one worktree at a time. Use a different branch, or --detach. After deleting a worktree directory manually, run git worktree prune to clear the dangling reference.

## 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: Usage, Options & Common CI Errors?

Worktrees avoid re-cloning when you need two branches checked out at once - handy for parallel CI builds.

### What it does?

git worktree creates additional working trees linked to the same repository, so you can have multiple branches checked out simultaneously without separate clones.

### Common errors in CI?

fatal: 'X' is already checked out at '…' - a branch can be checked out in only one worktree at a time. Use a different branch, or --detach. After deleting a worktree directory manually, run git worktree prune to clear the dangling reference.

---

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