man1/git-name-rev.1

   1 '\" t
   2 .\"     Title: git-name-rev
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 07/22/2022
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.37.1.223.g6a475b71f8
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-NAME\-REV" "1" "07/22/2022" "Git 2\&.37\&.1\&.223\&.g6a475b" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-name-rev \- Find symbolic names for given revs
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit name\-rev\fR [\-\-tags] [\-\-refs=<pattern>]
  36                ( \-\-all | \-\-stdin | <commit\-ish>\&... )
  37 .fi
  38 .sp
  39 .SH "DESCRIPTION"
  40 .sp
  41 Finds symbolic names suitable for human digestion for revisions given in any format parsable by \fIgit rev\-parse\fR\&.
  42 .SH "OPTIONS"
  43 .PP
  44 \-\-tags
  45 .RS 4
  46 Do not use branch names, but only tags to name the commits
  47 .RE
  48 .PP
  49 \-\-refs=<pattern>
  50 .RS 4
  51 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
  52 \fB\-\-no\-refs\fR
  53 to clear any previous ref patterns given\&.
  54 .RE
  55 .PP
  56 \-\-exclude=<pattern>
  57 .RS 4
  58 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
  59 \fB\-\-no\-exclude\fR
  60 to clear the list of exclude patterns\&.
  61 .RE
  62 .PP
  63 \-\-all
  64 .RS 4
  65 List all commits reachable from all refs
  66 .RE
  67 .PP
  68 \-\-annotate\-stdin
  69 .RS 4
  70 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\&.
  71 .sp
  72 For example:
  73 .sp
  74 .if n \{\
  75 .RS 4
  76 .\}
  77 .nf
  78 $ cat sample\&.txt
  79
  80 An abbreviated revision 2ae0a9cb82 will not be substituted\&.
  81 The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907,
  82 while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
  83
  84 $ git name\-rev \-\-annotate\-stdin <sample\&.txt
  85
  86 An abbreviated revision 2ae0a9cb82 will not be substituted\&.
  87 The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907 (master),
  88 while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
  89
  90 $ git name\-rev \-\-name\-only \-\-annotate\-stdin <sample\&.txt
  91
  92 An abbreviated revision 2ae0a9cb82 will not be substituted\&.
  93 The full name after substitution is master,
  94 while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
  95 .fi
  96 .if n \{\
  97 .RE
  98 .\}
  99 .sp
 100 .RE
 101 .PP
 102 \-\-stdin
 103 .RS 4
 104 This option is deprecated in favor of
 105 \fIgit name\-rev \-\-annotate\-stdin\fR\&. They are functionally equivalent\&.
 106 .RE
 107 .PP
 108 \-\-name\-only
 109 .RS 4
 110 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
 111 \fBgit\-describe\fR
 112 more closely\&.
 113 .RE
 114 .PP
 115 \-\-no\-undefined
 116 .RS 4
 117 Die with error code != 0 when a reference is undefined, instead of printing
 118 \fBundefined\fR\&.
 119 .RE
 120 .PP
 121 \-\-always
 122 .RS 4
 123 Show uniquely abbreviated commit object as fallback\&.
 124 .RE
 125 .SH "EXAMPLES"
 126 .sp
 127 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\&.
 128 .sp
 129 Enter \fIgit name\-rev\fR:
 130 .sp
 131 .if n \{\
 132 .RS 4
 133 .\}
 134 .nf
 135 % git name\-rev 33db5f4d9027a10e477ccf054b2c1ab94f74c85a
 136 33db5f4d9027a10e477ccf054b2c1ab94f74c85a tags/v0\&.99~940
 137 .fi
 138 .if n \{\
 139 .RE
 140 .\}
 141 .sp
 142 .sp
 143 Now you are wiser, because you know that it happened 940 revisions before v0\&.99\&.
 144 .sp
 145 Another nice thing you can do is:
 146 .sp
 147 .if n \{\
 148 .RS 4
 149 .\}
 150 .nf
 151 % git log | git name\-rev \-\-stdin
 152 .fi
 153 .if n \{\
 154 .RE
 155 .\}
 156 .sp
 157 .SH "GIT"
 158 .sp
 159 Part of the \fBgit\fR(1) suite