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.
git name-rev HEAD~2 git name-rev --tags abc1234 git log --format=%H | git name-rev --annotate-stdin
Try it
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.
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
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-revfinds a ref that contains the commit, so a commit on a deleted branch or an unreachable commit isundefined. --tagsand the newest commit. In the first exampleHEADis newer thanv1, so no tag contains it and the result isundefined; the same commit is namedmainwithout--tags.- Ref preference. Tags are preferred over branches because they are more stable; among branches, a shorter path (fewer
~and^steps) wins. Names with^0mean "the tagged commit itself" (the peeled tag). - Names change over time. A commit named
main~3today will bemain~4after the next commit. Do not store these names; store hashes. - Compare with
git describe.describelooks back from the commit to a tag and builds a version string;name-rev --tagslooks for the closest tag that contains it, givingv1.1~2style names after the commit. --annotate-stdinreplaces the old--stdinand rewrites any 40-character hash (or abbreviation that resolves) in the input withhash (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
--refsto avoid names based on temporary or remote branches (for example--refs='refs/heads/release/*').
Related
git describe,git rev-parse,git tag,git rev-list, Revision syntax- Lessons: Revisions, Tags