git name-rev

Reverse of rev-parse: SHA in, name out.

🎯 What & why

Given a commit SHA, print a human-readable name for it like main~3 or tags/v1.2~5. The reverse direction of rev-parse.

🧠 Mental model

Walks refs backwards looking for the nearest named ancestor, then expresses your commit as an offset from it. Great for log output, awful as a stable identifier (the name shifts as refs move).

🛠️ Synopsis

git name-rev [--tags] [--refs=<pattern>] [--exclude=<pattern>]
            [--all] [--annotate-stdin] [--name-only]
            [--no-undefined] [--always]
            <commit>...

🎚️ Switches & options

Flag	What it does
`<commit>...`	Commits (or anything resolving to one) to name.
`--tags`	Use only tags as anchors; ignores branches.
`--refs=<pattern>`	Restrict anchors to refs matching a glob, e.g. `refs/tags/v*`.
`--exclude=<pattern>`	Skip refs matching the glob (pair with --refs).
`--all`	Name every commit reachable from any ref; useful for bulk annotation.
`--annotate-stdin`	Read stdin and append a name after each SHA-shaped token (replaces older --stdin).
`--name-only`	Output just the name, not the SHA + name pair.
`--no-undefined`	Fail instead of printing `undefined` for unreachable commits.
`--always`	Fall back to an abbreviated SHA when no name is found.

💡 Use cases

Decorate log/diff output with human-readable names instead of bare SHAs.
Confirm which release a commit landed in by restricting anchors to refs/tags/*.
Pipe a stream of SHAs (e.g. from rev-list) through --annotate-stdin for readable reports.
Detect 'orphan' commits not reachable from any ref via --no-undefined.

🧪 Examples

Name a single commit

git name-rev abc1234

Name only against tags

git name-rev --tags --name-only abc1234

Annotate a log stream

git rev-list --max-count=20 HEAD | git name-rev --annotate-stdin

Restrict to release tags

git name-rev --refs='refs/tags/v*' HEAD~50

🎓 Recommendations

For machine-readable identifiers use git describe --always or a full SHA; name-rev output drifts as refs move.
Combine --tags --refs='refs/tags/v*' when answering 'which release contains this commit?' so feature branches don't pollute the answer.

🪤 Common pitfalls

Output is not stable; tomorrow's main~3 is today's main~4 after one new commit.
Without --no-undefined you can silently get the literal string undefined and not notice.
--annotate-stdin is the modern spelling; older docs/scripts using --stdin may break on newer Git.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.