blob: d4f1c4d5945e8ed38c243ecee0920bd6e38219a5 [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>]
John Cai9019d7d2023-05-06 04:14:11 +000013 ( --all | --annotate-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
Elijah Newren4d542682023-10-08 06:45:24 +000029 can be a branch name, a tag name, or a fully qualified ref name. If
Jacob Keller290be662017-01-18 15:06:05 -080030 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 Cai9019d7d2023-05-06 04:14:11 +000049 altogether. This option was called `--stdin` in older versions
50 of Git.
John Cai34ae3b72022-01-05 23:29:31 +000051+
52For example:
53+
54-----------
55$ cat sample.txt
56
57An abbreviated revision 2ae0a9cb82 will not be substituted.
58The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907,
59while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
60
61$ git name-rev --annotate-stdin <sample.txt
62
63An abbreviated revision 2ae0a9cb82 will not be substituted.
64The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907 (master),
65while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
66
67$ git name-rev --name-only --annotate-stdin <sample.txt
68
69An abbreviated revision 2ae0a9cb82 will not be substituted.
70The full name after substitution is master,
71while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
72-----------
73
Shawn O. Pearce23615702007-05-21 03:20:25 -040074--name-only::
75 Instead of printing both the SHA-1 and the name, print only
76 the name. If given with --tags the usual tag prefix of
Brian Hetro02783072007-08-23 20:44:13 -040077 "tags/" is also omitted from the name, matching the output
Junio C Hamano372c7672008-08-02 11:58:34 -070078 of `git-describe` more closely.
Shawn O. Pearce23615702007-05-21 03:20:25 -040079
Stephan Beyereba13512008-06-08 03:36:12 +020080--no-undefined::
81 Die with error code != 0 when a reference is undefined,
82 instead of printing `undefined`.
83
84--always::
85 Show uniquely abbreviated commit object as fallback.
86
Nguyễn Thái Ngọc Duy76a87882018-04-30 17:35:33 +020087EXAMPLES
88--------
Johannes Schindelinbd321bc2005-10-26 15:10:20 +020089
90Given a commit, find out where it is relative to the local refs. Say somebody
Alp Toker2a758482006-07-11 11:19:33 +010091wrote you about that fantastic commit 33db5f4d9027a10e477ccf054b2c1ab94f74c85a.
Johannes Schindelinbd321bc2005-10-26 15:10:20 +020092Of course, you look into the commit, but that only tells you what happened, but
93not the context.
94
Thomas Rast0b444cd2010-01-10 00:33:00 +010095Enter 'git name-rev':
Johannes Schindelinbd321bc2005-10-26 15:10:20 +020096
97------------
98% git name-rev 33db5f4d9027a10e477ccf054b2c1ab94f74c85a
Junio C Hamanoee837242008-08-30 13:08:50 -07009933db5f4d9027a10e477ccf054b2c1ab94f74c85a tags/v0.99~940
Johannes Schindelinbd321bc2005-10-26 15:10:20 +0200100------------
101
102Now you are wiser, because you know that it happened 940 revisions before v0.99.
103
104Another nice thing you can do is:
105
106------------
John Cai9019d7d2023-05-06 04:14:11 +0000107% git log | git name-rev --annotate-stdin
Johannes Schindelinbd321bc2005-10-26 15:10:20 +0200108------------
109
Johannes Schindelinbd321bc2005-10-26 15:10:20 +0200110GIT
111---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200112Part of the linkgit:git[1] suite