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

> git worktree list shows every working tree linked to the repo, with paths and branches. Reference for --porcelain and detecting stale or locked trees in CI.

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

git worktree list shows all working trees attached to the repository and what each has checked out.

When a job juggles several worktrees, list is how you discover what exists, where, and on which branch - with a stable --porcelain format for scripts.

## What it does

git worktree list prints each linked working tree with its path, current HEAD, and checked-out branch, flagging bare, detached, locked, or prunable trees.

## Common usage

```Terminal
git worktree list
git worktree list --porcelain
git worktree list -v             # show lock/prunable reasons
```

## Options

| Flag | What it does |
| --- | --- |
| --porcelain | Stable, machine-readable output |
| -v / --verbose | Show extra annotations (locked, prunable) |
| -z | NUL-terminate records (with --porcelain) |

## Common errors in CI

A worktree whose directory was deleted manually still appears as "prunable" until you run git worktree prune; parse --porcelain (not the human format) so a stale entry does not break a script. The main worktree is always listed 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 list: Usage, Options & Common CI Errors?

When a job juggles several worktrees, list is how you discover what exists, where, and on which branch - with a stable --porcelain format for scripts.

### What it does?

git worktree list prints each linked working tree with its path, current HEAD, and checked-out branch, flagging bare, detached, locked, or prunable trees.

### Common errors in CI?

A worktree whose directory was deleted manually still appears as "prunable" until you run git worktree prune; parse --porcelain (not the human format) so a stale entry does not break a script. The main worktree is always listed 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