git worktree list: Usage, Options & Common CI Errors

By Daniel Zoghalchali·Latchkey

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

Frequently asked questions

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