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

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.

Related guides

git for-each-ref: Usage, Options & Common CI Errorsgit for-each-ref iterates over refs with a custom format. Reference for --format, --sort, --points-at, and bu… git update-ref: Usage, Options & Common CI Errorsgit update-ref creates, updates, or deletes a ref with old-value checks. Reference for -d, --create-reflog, s… git symbolic-ref: Usage, Options & Common CI Errorsgit symbolic-ref reads and writes symbolic refs like HEAD, used to find or set the default branch. Reference… git rev-parse: Usage, Options & Common CI Errorsgit rev-parse resolves refs to SHAs and reports repo paths - core CI plumbing. Reference for --short, --abbre…