git "error: pathspec ... did not match" (fetch-depth) in CI

git could not resolve the branch, tag, or commit you passed to git checkout because it is not present in the local clone. A shallow clone fetched only one ref, so any other ref you name is unknown.

What this error means

A git checkout main or git checkout v1.2.3 step fails with "error: pathspec 'main' did not match any file(s) known to git", even though the ref exists on the remote.

git

error: pathspec 'v1.2.3' did not match any file(s) known to git

Common causes

The ref was never fetched by a shallow clone

Default fetch-depth 1 fetches only the checked-out ref. A different branch or a tag was not downloaded, so git checkout cannot find it.

Tags were not fetched

Even with more depth, tags are not fetched unless requested, so checking out a tag name fails with pathspec mismatch.

How to fix it

Fetch full history and tags

Pull all history and tags so any ref you check out is present locally.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
    fetch-tags: true

Fetch the specific ref before checkout

If you keep a shallow clone, fetch the branch or tag explicitly first.

Terminal

git fetch --depth 1 origin v1.2.3
git checkout v1.2.3

How to prevent it

Use fetch-depth: 0 when the job checks out branches or tags other than the trigger ref.
Set fetch-tags: true when you check out or describe by tag.
Fetch a ref before checking it out in a shallow clone.