# git worktree --detach: Parallel Checkouts in CI

> git worktree add --detach checks out a second working tree without claiming a branch, ideal for building two refs side by side in CI. Reference for flags and errors.

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

git worktree add --detach <path> <commit> creates a second working tree at a detached HEAD so a job can have two checkouts at once.

When a build needs the base branch and the PR branch on disk simultaneously, a detached worktree avoids a second clone. The --detach flag skips branch checkout so the same branch can stay checked out in the main tree.

## What it does

git worktree add attaches an extra working directory linked to the same .git. With --detach it checks out the given commit at a detached HEAD instead of a branch, which lets you materialize a ref that is already checked out elsewhere (git refuses to check the same branch out in two trees).

## Common usage

```Terminal
git worktree add --detach ../base origin/main
git worktree add -b pr-123 ../pr origin/pr-123
# clean up when the job is done
git worktree remove ../base
git worktree prune
```

## Options

| Flag | What it does |
| --- | --- |
| --detach | Check out at a detached HEAD instead of a branch |
| -b <branch> | Create and check out a new branch in the worktree |
| --force | Allow adding even if the path or branch is in use |
| list | List existing worktrees and their HEADs |
| remove <path> | Delete a worktree |
| prune | Remove administrative entries for deleted worktrees |

## In CI

On a shallow clone (fetch-depth: 1) the commit you target may not exist locally; fetch it first with git fetch --depth 1 origin <ref>. Always git worktree remove or prune before the job ends so cached checkouts on a persistent runner do not accumulate stale .git/worktrees entries.

## Common errors in CI

"fatal: 'origin/main' is already checked out at ..." means you tried to attach the branch in a second tree; use --detach. "fatal: invalid reference: origin/pr-123" on a shallow clone means the ref was never fetched. "fatal: '../base' already exists" means a leftover worktree from a prior run; prune or remove it first.

## 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 --detach: Parallel Checkouts in CI?

When a build needs the base branch and the PR branch on disk simultaneously, a detached worktree avoids a second clone. The --detach flag skips branch checkout so the same branch can stay checked out in the main tree.

### What it does?

git worktree add attaches an extra working directory linked to the same .git. With --detach it checks out the given commit at a detached HEAD instead of a branch, which lets you materialize a ref that is already checked out elsewhere (git refuses to check the same branch out in two trees).

### In CI?

On a shallow clone (fetch-depth: 1) the commit you target may not exist locally; fetch it first with git fetch --depth 1 origin <ref>. Always git worktree remove or prune before the job ends so cached checkouts on a persistent runner do not accumulate stale .git/worktrees entries.

### Common errors in CI?

"fatal: 'origin/main' is already checked out at ..." means you tried to attach the branch in a second tree; use --detach. "fatal: invalid reference: origin/pr-123" on a shallow clone means the ref was never fetched. "fatal: '../base' already exists" means a leftover worktree from a prior run; prune or remove it first.

---

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