blob: ec8a27ce8bf8d689bb5f64554dd5426ce38262c0 [file] [log] [blame]
Johannes Schindelinbd321bc2005-10-26 15:10:20 +02001git-name-rev(1)
2===============
3
4NAME
5----
Fredrik Kuivinen7bd7f282006-03-09 17:24:50 +01006git-name-rev - Find symbolic names for given revs
Johannes Schindelinbd321bc2005-10-26 15:10:20 +02007
8
9SYNOPSIS
10--------
Matthias Kestenholze448ff82007-05-18 15:39:33 +020011[verse]
Jonathan Niederb1889c32008-06-30 01:09:04 -050012'git name-rev' [--tags] [--refs=<pattern>]
Richard Hansena8a54062013-09-04 15:04:31 -040013 ( --all | --stdin | <commit-ish>... )
Johannes Schindelinbd321bc2005-10-26 15:10:20 +020014
15DESCRIPTION
16-----------
17Finds symbolic names suitable for human digestion for revisions given in any
Thomas Rast0b444cd2010-01-10 00:33:00 +010018format parsable by 'git rev-parse'.
Johannes Schindelinbd321bc2005-10-26 15:10:20 +020019
20
21OPTIONS
22-------
23
24--tags::
25 Do not use branch names, but only tags to name the commits
26
Johannes Schindelin2afc29a2007-02-17 19:22:35 +010027--refs=<pattern>::
Namhyung Kim98c5c4a2013-06-18 21:35:31 +090028 Only use refs whose names match a given shell pattern. The pattern
Jacob Keller290be662017-01-18 15:06:05 -080029 can be one of branch name, tag name or fully qualified ref name. If
30 given multiple times, use refs whose names match any of the given shell
31 patterns. Use `--no-refs` to clear any previous ref patterns given.
Johannes Schindelin2afc29a2007-02-17 19:22:35 +010032
Jacob Keller96415b42017-01-18 15:06:06 -080033--exclude=<pattern>::
34 Do not use any ref whose name matches a given shell pattern. The
35 pattern can be one of branch name, tag name or fully qualified ref
36 name. If given multiple times, a ref will be excluded when it matches
37 any of the given patterns. When used together with --refs, a ref will
38 be used as a match only when it matches at least one --refs pattern and
39 does not match any --exclude patterns. Use `--no-exclude` to clear the
40 list of exclude patterns.
41
Johannes Schindelinbd321bc2005-10-26 15:10:20 +020042--all::
43 List all commits reachable from all refs
44
John Cai34ae3b72022-01-05 23:29:31 +000045--annotate-stdin::
Ramkumar Ramachandra3087b612013-07-07 18:13:16 +053046 Transform stdin by substituting all the 40-character SHA-1
47 hexes (say $hex) with "$hex ($rev_name)". When used with
48 --name-only, substitute with "$rev_name", omitting $hex
John Cai34ae3b72022-01-05 23:29:31 +000049 altogether.
50+
51For example:
52+
53-----------
54$ cat sample.txt
55
56An abbreviated revision 2ae0a9cb82 will not be substituted.
57The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907,
58while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
59
60$ git name-rev --annotate-stdin <sample.txt
61
62An abbreviated revision 2ae0a9cb82 will not be substituted.
63The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907 (master),
64while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
65
66$ git name-rev --name-only --annotate-stdin <sample.txt
67
68An abbreviated revision 2ae0a9cb82 will not be substituted.
69The full name after substitution is master,
70while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
71-----------
72
73--stdin::
74 This option is deprecated in favor of 'git name-rev --annotate-stdin'.
75 They are functionally equivalent.
Johannes Schindelinbd321bc2005-10-26 15:10:20 +020076
Shawn O. Pearce23615702007-05-21 03:20:25 -040077--name-only::
78 Instead of printing both the SHA-1 and the name, print only
79 the name. If given with --tags the usual tag prefix of
Brian Hetro02783072007-08-23 20:44:13 -040080 "tags/" is also omitted from the name, matching the output
Junio C Hamano372c7672008-08-02 11:58:34 -070081 of `git-describe` more closely.
Shawn O. Pearce23615702007-05-21 03:20:25 -040082
Stephan Beyereba13512008-06-08 03:36:12 +020083--no-undefined::
84 Die with error code != 0 when a reference is undefined,
85 instead of printing `undefined`.
86
87--always::
88 Show uniquely abbreviated commit object as fallback.
89
Nguyễn Thái Ngọc Duy76a87882018-04-30 17:35:33 +020090EXAMPLES
91--------
Johannes Schindelinbd321bc2005-10-26 15:10:20 +020092
93Given a commit, find out where it is relative to the local refs. Say somebody
Alp Toker2a758482006-07-11 11:19:33 +010094wrote you about that fantastic commit 33db5f4d9027a10e477ccf054b2c1ab94f74c85a.
Johannes Schindelinbd321bc2005-10-26 15:10:20 +020095Of course, you look into the commit, but that only tells you what happened, but
96not the context.
97
Thomas Rast0b444cd2010-01-10 00:33:00 +010098Enter 'git name-rev':
Johannes Schindelinbd321bc2005-10-26 15:10:20 +020099
100------------
101% git name-rev 33db5f4d9027a10e477ccf054b2c1ab94f74c85a
Junio C Hamanoee837242008-08-30 13:08:50 -070010233db5f4d9027a10e477ccf054b2c1ab94f74c85a tags/v0.99~940
Johannes Schindelinbd321bc2005-10-26 15:10:20 +0200103------------
104
105Now you are wiser, because you know that it happened 940 revisions before v0.99.
106
107Another nice thing you can do is:
108
109------------
110% git log | git name-rev --stdin
111------------
112
Johannes Schindelinbd321bc2005-10-26 15:10:20 +0200113GIT
114---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200115Part of the linkgit:git[1] suite