Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Branches and Tags

git name-rev command

Reference for git name-rev: translate commit hashes to names like v1.0~3 or main~2, use --tags, --name-only, --refs and --annotate-stdin to label text.

git name-rev answers "which branch or tag is this commit near?" Given a hash, it finds a ref from which the commit is reachable and prints a name such as main~3 or tags/v1.0^0. It is the reverse of resolving a name to a hash, and unlike git describe it searches forward from refs to the commit, so it can name any commit that some ref contains.

It is mostly used to make hashes in logs, error messages and scripts readable.

Terminal
git name-rev HEAD~2
git name-rev --tags abc1234
git log --format=%H | git name-rev --annotate-stdin

Try it

Bash Naming commits

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 Annotating text with names

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 name-rev [--tags] [--refs=<pattern>]... [--exclude=<pattern>]...
             ( --all | --annotate-stdin | <commit-ish>... )
             [--name-only] [--no-undefined] [--always]
Name Description
<commit-ish>... Revisions to name.
--tags Use only tags for naming and drop the tags/ prefix.
--refs=<pattern> Only consider refs matching the glob; repeatable.
--exclude=<pattern> Ignore refs matching the glob.
--all List every reachable commit with its name.
--annotate-stdin Read text from standard input and append names after each full or abbreviated hash.
--name-only Print only the name, not the hash.
--no-undefined Exit with an error if a commit cannot be named.
--always Show an abbreviated hash for commits that have no name.

Returns: lines like <hash> main~2; commits that cannot be named print undefined.

Errors: with --no-undefined, a commit that cannot be named makes it fail with a non-zero exit status. Passing an object that is not a commit prints "Could not get sha1" or "Could not get object" and skips it.

Usage notes

  • Forward search. name-rev finds a ref that contains the commit, so a commit on a deleted branch or an unreachable commit is undefined.
  • --tags and the newest commit. In the first example HEAD is newer than v1, so no tag contains it and the result is undefined; the same commit is named main without --tags.
  • Ref preference. Tags are preferred over branches because they are more stable; among branches, a shorter path (fewer ~ and ^ steps) wins. Names with ^0 mean "the tagged commit itself" (the peeled tag).
  • Names change over time. A commit named main~3 today will be main~4 after the next commit. Do not store these names; store hashes.
  • Compare with git describe. describe looks back from the commit to a tag and builds a version string; name-rev --tags looks for the closest tag that contains it, giving v1.1~2 style names after the commit.
  • --annotate-stdin replaces the old --stdin and rewrites any 40-character hash (or abbreviation that resolves) in the input with hash (name).
  • Performance: the tool walks the history once from all refs, so it is fast even for large lists, much faster than calling it per hash.
  • Use --refs to avoid names based on temporary or remote branches (for example --refs='refs/heads/release/*').