Git show-ref: Inspect Local References

Advanced

What `git show-ref` observes

A Git repository has named references such as local branches, remote-tracking refs, and tags. `git show-ref` lists refs together with the object ID they name. It is a reference-inspection command: it does not create, move, or delete the refs it displays.

git show-ref
git show-ref --heads
git show-ref --tags

?

Filter by local branches and tags

`--heads` limits output to local branch refs, while `--tags` limits output to local tag refs. These filters can be combined when you want branches and tags but not other refs.

git show-ref --heads
git show-ref --tags
git show-ref --heads --tags

?

Patterns are not exact ref verification

A trailing pattern can select refs by matching complete path components from the end of the full ref name. This is useful for discovery, but it is not the same as exact verification. A pattern such as `main` can match a branch or other ref whose name ends in the corresponding component.

git show-ref main
git show-ref --verify refs/heads/main

?

Exact existence checks

`git show-ref --exists <ref>` tests whether a reference exists without requiring the reference to resolve to an object. In the tested Git 2.47.3, exit status 0 means the ref exists and status 2 means it does not exist. This is distinct from `--verify`, which performs stricter ref checking.

git show-ref --exists refs/heads/main
echo $?
git show-ref --exists refs/heads/does-not-exist
echo $?

?

Quiet verification for scripts

`--verify --quiet` suppresses normal output and leaves the result in the process exit status. This is useful when a shell script needs a yes/no test rather than the object ID and ref name.

if git show-ref --quiet --verify refs/heads/main; then
  echo 'main exists'
else
  echo 'main is absent'
fi

?

Dereference annotated tags

With `--tags --dereference`, annotated tags are followed to the object they name, producing an additional line for the dereferenced object. Lightweight tags do not have a tag object to dereference.

git show-ref --tags --dereference

?

Inspect only the object IDs

`--hash` changes the output from `<object-id> <ref>` to object IDs alone. An optional abbreviation length can be supplied. This is useful when a script needs IDs rather than the ref names themselves.

git show-ref --heads --hash
git show-ref --heads --hash=12

?

The stdin filter: `--exclude-existing`

`--exclude-existing` changes `show-ref` into a filter. It reads ref names from standard input and outputs only refs that do not already exist locally. This is useful when comparing a proposed ref set with the repository's existing namespace.

printf '%s\n' refs/heads/main refs/heads/new-topic | git show-ref --exclude-existing

?

HEAD and repository ref storage

`--head` explicitly includes `HEAD` in the listing even when normal filtering would omit it. The command reads Git's reference namespace rather than requiring you to inspect `.git/refs` and `.git/packed-refs` yourself. This remains useful whether a ref is loose or packed.

git show-ref --head
git pack-refs --all
git show-ref --head

?

Boundaries with related commands

Keep the ownership boundaries clear. `git show-ref` reports refs; `git symbolic-ref` reads or changes symbolic refs such as `HEAD`; `git update-ref` performs ref updates; `git for-each-ref` provides programmable ref iteration; `git ls-remote` inspects refs advertised by another repository. `git show-ref` is therefore an inspection primitive, not a general ref-editing command.

git show-ref
git symbolic-ref --short HEAD
git for-each-ref --format='%(refname)'

?

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.