# git show-ref: Usage, Options & Common CI Errors

> git show-ref lists refs and their object ids, and verifies a ref exists. Reference for --verify, --tags, --heads, and the not-a-valid-ref CI gate error.

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

git show-ref lists references with their SHAs and can confirm a specific ref exists.

show-ref is the scriptable way to ask "does this branch/tag exist and what does it point to?" without parsing branch or tag output - its --verify mode is a clean CI existence gate.

## What it does

git show-ref prints each matching reference as "<sha> <refname>". With --verify it checks one exact ref and exits non-zero if it is missing, making it a reliable presence test.

## Common usage

```Terminal
git show-ref
git show-ref --tags
git show-ref --heads
git show-ref --verify --quiet refs/heads/main && echo "exists"
git show-ref refs/tags/v1.2.0
```

## Options

| Flag | What it does |
| --- | --- |
| --verify | Require an exact, full refname |
| --heads / --tags | Limit to branches / tags |
| -q / --quiet | No output; rely on exit code |
| --hash | Print only the object id |
| -d / --dereference | Also show what tags dereference to |

## Common errors in CI

fatal: ‘<ref>’ - not a valid ref - with --verify you must pass the full path (refs/heads/main, not main). A missing ref simply exits non-zero with --quiet, which is the intended gate signal. Shallow/single-branch clones may legitimately lack the ref you are checking.

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

show-ref is the scriptable way to ask "does this branch/tag exist and what does it point to?" without parsing branch or tag output - its --verify mode is a clean CI existence gate.

### What it does?

git show-ref prints each matching reference as "<sha> <refname>". With --verify it checks one exact ref and exits non-zero if it is missing, making it a reliable presence test.

### Common errors in CI?

fatal: ‘<ref>’ - not a valid ref - with --verify you must pass the full path (refs/heads/main, not main). A missing ref simply exits non-zero with --quiet, which is the intended gate signal. Shallow/single-branch clones may legitimately lack the ref you are checking.

---

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