'\" t
.\"     Title: git-name-rev
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 01/13/2023
.\"    Manual: Git Manual
.\"    Source: Git 2.39.1
.\"  Language: English
.\"
.TH "GIT\-NAME\-REV" "1" "01/13/2023" "Git 2\&.39\&.1" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-name-rev \- Find symbolic names for given revs
.SH "SYNOPSIS"
.sp
.nf
\fIgit name\-rev\fR [\-\-tags] [\-\-refs=<pattern>]
               ( \-\-all | \-\-stdin | <commit\-ish>\&... )
.fi
.sp
.SH "DESCRIPTION"
.sp
Finds symbolic names suitable for human digestion for revisions given in any format parsable by \fIgit rev\-parse\fR\&.
.SH "OPTIONS"
.PP
\-\-tags
.RS 4
Do not use branch names, but only tags to name the commits
.RE
.PP
\-\-refs=<pattern>
.RS 4
Only use refs whose names match a given shell pattern\&. The pattern can be one of branch name, tag name or fully qualified ref name\&. If given multiple times, use refs whose names match any of the given shell patterns\&. Use
\fB\-\-no\-refs\fR
to clear any previous ref patterns given\&.
.RE
.PP
\-\-exclude=<pattern>
.RS 4
Do not use any ref whose name matches a given shell pattern\&. The pattern can be one of branch name, tag name or fully qualified ref name\&. If given multiple times, a ref will be excluded when it matches any of the given patterns\&. When used together with \-\-refs, a ref will be used as a match only when it matches at least one \-\-refs pattern and does not match any \-\-exclude patterns\&. Use
\fB\-\-no\-exclude\fR
to clear the list of exclude patterns\&.
.RE
.PP
\-\-all
.RS 4
List all commits reachable from all refs
.RE
.PP
\-\-annotate\-stdin
.RS 4
Transform stdin by substituting all the 40\-character SHA\-1 hexes (say $hex) with "$hex ($rev_name)"\&. When used with \-\-name\-only, substitute with "$rev_name", omitting $hex altogether\&.
.sp
For example:
.sp
.if n \{\
.RS 4
.\}
.nf
$ cat sample\&.txt

An abbreviated revision 2ae0a9cb82 will not be substituted\&.
The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907,
while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad

$ git name\-rev \-\-annotate\-stdin <sample\&.txt

An abbreviated revision 2ae0a9cb82 will not be substituted\&.
The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907 (master),
while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad

$ git name\-rev \-\-name\-only \-\-annotate\-stdin <sample\&.txt

An abbreviated revision 2ae0a9cb82 will not be substituted\&.
The full name after substitution is master,
while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
\-\-stdin
.RS 4
This option is deprecated in favor of
\fIgit name\-rev \-\-annotate\-stdin\fR\&. They are functionally equivalent\&.
.RE
.PP
\-\-name\-only
.RS 4
Instead of printing both the SHA\-1 and the name, print only the name\&. If given with \-\-tags the usual tag prefix of "tags/" is also omitted from the name, matching the output of
\fBgit\-describe\fR
more closely\&.
.RE
.PP
\-\-no\-undefined
.RS 4
Die with error code != 0 when a reference is undefined, instead of printing
\fBundefined\fR\&.
.RE
.PP
\-\-always
.RS 4
Show uniquely abbreviated commit object as fallback\&.
.RE
.SH "EXAMPLES"
.sp
Given a commit, find out where it is relative to the local refs\&. Say somebody wrote you about that fantastic commit 33db5f4d9027a10e477ccf054b2c1ab94f74c85a\&. Of course, you look into the commit, but that only tells you what happened, but not the context\&.
.sp
Enter \fIgit name\-rev\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
% git name\-rev 33db5f4d9027a10e477ccf054b2c1ab94f74c85a
33db5f4d9027a10e477ccf054b2c1ab94f74c85a tags/v0\&.99~940
.fi
.if n \{\
.RE
.\}
.sp
.sp
Now you are wiser, because you know that it happened 940 revisions before v0\&.99\&.
.sp
Another nice thing you can do is:
.sp
.if n \{\
.RS 4
.\}
.nf
% git log | git name\-rev \-\-stdin
.fi
.if n \{\
.RE
.\}
.sp
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite