git-show-ref Tutorial

The short version

git-show-ref is used to list refs and the objects they point to.

When it is a good fit

• when you need to list refs and the objects they point to
• when you want this step to be repeatable instead of ad hoc
• when you need a clearer mental model of what Git is recording or updating

Basic example

git show-ref --heads --tags

What to watch most closely

Learn the default behavior first. Many surprises come from adding flags before the base behavior is clear.

A safer working habit

Pair it with status, log, or diff so you can confirm what actually changed.

Useful angles for understanding it

• Understand the default behavior clearly
• Use it in day-to-day Git routines
• Reuse it safely in scripts or team habits

Related reading

Read it alongside git status, git log, and git show so it is easier to see how the command changes history, refs, the index, or the working tree.

What problem this command solves in a workflow

git show-ref solves the problem of "I need to see all references in the repository and their target commit hashes." It lists all local branches, tags, and remote-tracking refs along with the commit hashes they point to.

Typical use cases

• When diagnosing branch pointer issues, use git show-ref --heads to list all local branches and their target commits, confirming whether branches point at the expected commits.
• Use git show-ref --tags to view all tags and their corresponding commit hashes, verifying tag versions are correct.
• In scripts, check whether a ref exists using git show-ref --verify refs/heads/main and act conditionally based on the exit code.

Diagram view

Repository refs

Local branchesTagsRemote-tracking refsPacked-refs

→git show-ref

Output

Ref namesTarget commit hashesRef existence verification

show-ref only shows refs in the local repository — it does not contact the remote server for updated remote ref info.

Special cases and boundaries

• git show-ref only reads refs in the local repository (.git/refs and packed-refs); it does not contact the remote server for updated remote-tracking info.
• It is a purely read-only command that does not modify anything in the repository.
• In --verify mode, you can check whether a specific ref exists — it returns a non-zero exit code if the ref does not exist, suitable for conditional logic in scripts.
• HEAD itself is not a normal ref; git show-ref does not display HEAD by default — use --head to include it.
• If refs are packed in the packed-refs file (common in repos with many refs), show-ref reads them correctly regardless.