Git name-rev: Find Symbolic Names for Commits

Advanced

What `git name-rev` does

`git name-rev` takes revisions that Git can parse and finds symbolic names for them based on local refs. The result answers a contextual question such as: which branch or tag gives a useful name to this commit, and how far back is the commit from that ref?

git name-rev HEAD
git name-rev HEAD~2

?

How the name is chosen

The command considers refs that can name the supplied revision. A result can use a branch or tag name followed by a revision distance, such as `main~2`. The name is a description relative to a reachable ref; it is not a new ref and it does not modify repository history.

git name-rev HEAD~3

?

Restrict naming to tags

Use `--tags` when the naming context should come from tags rather than branches. This is useful when you want a revision described relative to release-like tag refs.

git name-rev --tags HEAD

?

Restrict the refs with a pattern

`--refs=<pattern>` limits the refs considered for naming. The pattern is matched against ref names, so you can deliberately choose the namespace or family of refs that should provide names.

git name-rev --refs='refs/heads/release/*' HEAD

?

Name only

`--name-only` suppresses the object ID and prints only the symbolic name. This is useful in scripts when the name itself is the desired value.

git name-rev --name-only HEAD

?

Process all reachable commits

`--all` asks `git name-rev` to process all commits reachable from all refs. This is useful for generating a broad map from commit IDs to symbolic names, but it can produce substantially more output than naming one revision.

git name-rev --all

?

Annotate text from standard input

`--annotate-stdin` reads text from standard input and annotates recognizable full commit IDs with their symbolic names. This makes `git name-rev` useful in diagnostic or reporting pipelines where commit IDs are already embedded in text.

printf '%s\n' "commit $(git rev-parse HEAD)" | git name-rev --annotate-stdin
printf '%s\n' "commit $(git rev-parse HEAD)" | git name-rev --name-only --annotate-stdin

?

Undefined revisions and fallback names

By default, an input revision that cannot be given a ref-based name may be reported as `undefined`. `--no-undefined` instead makes undefined naming an error. `--always` provides a uniquely abbreviated object name as a fallback when no symbolic name is available.

git name-rev HEAD~999 2>/dev/null || true
git name-rev --no-undefined HEAD~999 2>/dev/null || true
git name-rev --always HEAD

?

`git name-rev` versus nearby commands

`git name-rev` is about assigning symbolic names to already-selected revisions. The existing revision-names-and-ranges curriculum owns the syntax used to select revisions; `git rev-parse` parses and verifies revision names and other parameters; `git show-ref` inspects local refs. `git describe` has a different purpose and selection strategy. Keeping those responsibilities separate prevents this lesson from duplicating the revision-selection curriculum.

Practice what you learned

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