git-name-rev

Show the name for HEAD

$ git name-rev HEAD

$ git name-rev --name-only HEAD

$ git name-rev --all

$ git name-rev --tags HEAD

$ git name-rev --no-undefined [commit-ish]

$ git name-rev HEAD~1 HEAD~2 main

$ git name-rev --refs refs/heads/ [commit-ish]

$ echo "[commit-ish]" | git name-rev --annotate-stdin

git name-rev [--stdin] [--tags] [--name-only] [--refs[=<pattern>]] (rev | range)...

--stdin
    Read commit hashes from stdin (one per line); outputs names to stdout.

--tags
    Include and prefer annotated tags as if listed on command line.

--name-only
    Output only ref name; omit '~<n>' distance suffix.

--refs[=<pattern>]
    Limit to refs matching glob pattern (default: refs/).

git name-rev translates opaque Git commit hashes into human-readable symbolic names, such as branch names (e.g., main), tags (e.g., v2.1.0), or relative references (e.g., main~42 or v2.1.0~5). This simplifies identifying commits in logs, scripts, or communication.

It finds the closest ref (branch or tag) to the target commit by distance, preferring branches over tags by default. The output format is refname~distance, where distance is the number of commits back from the ref.

Ideal for piping with commands like git log --pretty=format:%H | git name-rev --stdin --name-only --tags, which annotates commit lists. Supports single commits, ranges, or batch input via stdin. Results prioritize shorter, more recent refs for readability.

However, names are heuristic: not always unique, and can change if refs move (e.g., fast-forwarded branches). Best for transient display, not permanent storage.

Names are lossy heuristics: not unique, unstable if refs move/delete.
Slow on large repos with many refs.
Prefers branches over tags unless --tags used.

git name-rev HEAD
main~3

git log --oneline | git name-rev --stdin --tags --name-only
Annotates log commits with names.

Selects shortest path via breadth-first search from refs.
Exact ref if commit matches; else appends '~n' for steps back.

Added in Git 1.5.3 (2007) by Johannes Schindelin for readable rev output.
--stdin added in 1.6.0; --refs in 1.7.6.
Default shifted from tag-preferring (pre-2.6) to branch-preferring for stability.

git-describe(1), git-rev-parse(1), git-show-ref(1), git-for-each-ref(1)