Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Branches and Tags

git show-ref command

Reference for git show-ref: list branches, tags and other refs with their object ids, verify that a ref exists, dereference tags and use exit codes in scripts.

git show-ref lists the refs in a repository together with the object ids they point to. Unlike git branch and git tag, it prints plain lines of <id> <full ref name> that are easy to parse, and it covers every ref namespace: branches, tags, remote-tracking branches and stashes.

Its second job is checking. With --verify or --exists it answers "does this exact ref exist?" through the exit status, which is the safest way to test for a branch or tag in a shell script.

Terminal
git show-ref                       # all refs
git show-ref --heads --tags        # only branches and tags
git show-ref --verify -q refs/heads/main && echo yes

Try it

Bash Listing and filtering refs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Verifying refs in a script

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git show-ref [--branches] [--tags] [--head] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [-q | --quiet] [--] [<pattern>...]
git show-ref --verify [-q] [-d] [-s] [--] <ref>...
git show-ref --exists <ref>
git show-ref --exclude-existing[=<pattern>]
Name Description
--branches Show only refs/heads/. (The older spelling --heads still works but is deprecated.)
--tags Show only refs/tags/.
--head Include HEAD in the list, even if it would be filtered out.
-d, --dereference For annotated tags, add an extra line <ref>^{} with the commit the tag points to.
-s, --hash[=<n>] Print only the object id, optionally shortened to n digits.
--abbrev[=<n>] Abbreviate the ids to at least n digits.
--verify Require each argument to be an exact, full ref name; fail otherwise.
--exists Check that one exact ref exists. Exit 2 if it is missing, 128 on other errors.
-q, --quiet Print nothing; use only the exit status.
--exclude-existing Filter stdin: print refs from the input that do not exist yet.
<pattern> Match refs by the trailing parts of their names.

Exit status: 0 when at least one ref matched, 1 when nothing matched. --verify exits 128 with a fatal message when a ref is missing, unless -q is given; --exists uses 2 for "not found".

Usage notes

  • Patterns match from the end. git show-ref main matches refs/heads/main and also refs/remotes/origin/main, but not a ref called refs/heads/domain. The match is by whole path components.
  • A bare name is not a safe existence test. A pattern can match a branch, a tag and a remote branch at once. In scripts use --verify with the full name, as shown above.
  • Annotated tags list the tag object. The id on the refs/tags/v2 line is the tag object; -d adds the ^{} line with the commit. Compare with git rev-parse v2^{commit}.
  • Packed and loose refs are both listed, and the output is sorted by ref name.
  • Stashes appear as refs/stash only for the newest entry; older ones live in the reflog.
  • Remote state is local. Remote-tracking refs show what you last fetched. To query the server use git ls-remote.
  • Heavier formatting (dates, authors, sorting by date) belongs to git for-each-ref.