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.
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@v4with:fetch-depth:0 # history, tags, and git describe all need this- run:|git rev-parse --is-shallow-repository # expect falsegit rev-parse --abbrev-ref HEAD # prints HEAD when detached
Frequently asked questions
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.
