[thirdparty/git.git] / Documentation / git-name-rev.txt

git-name-rev(1)
===============

NAME
----
git-name-rev - Find symbolic names for given revs


SYNOPSIS
--------
[verse]
'git name-rev' [--tags] [--refs=<pattern>]
	       ( --all | --stdin | <commit-ish>... )

DESCRIPTION
-----------
Finds symbolic names suitable for human digestion for revisions given in any
format parsable by 'git rev-parse'.


OPTIONS
-------

--tags::
	Do not use branch names, but only tags to name the commits

--refs=<pattern>::
	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 `--no-refs` to clear any previous ref patterns given.

--exclude=<pattern>::
	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 `--no-exclude` to clear the
	list of exclude patterns.

--all::
	List all commits reachable from all refs

--stdin::
	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.  Intended for the scripter's use.

--name-only::
	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 `git-describe` more closely.

--no-undefined::
	Die with error code != 0 when a reference is undefined,
	instead of printing `undefined`.

--always::
	Show uniquely abbreviated commit object as fallback.

EXAMPLES
--------

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.

Enter 'git name-rev':

------------
% git name-rev 33db5f4d9027a10e477ccf054b2c1ab94f74c85a
33db5f4d9027a10e477ccf054b2c1ab94f74c85a tags/v0.99~940
------------

Now you are wiser, because you know that it happened 940 revisions before v0.99.

Another nice thing you can do is:

------------
% git log | git name-rev --stdin
------------

GIT
---
Part of the linkgit:git[1] suite
Commit	Line	Data
bd321bcc JS	1	git-name-rev(1)
	2	===============
	3
	4	NAME
	5	----
7bd7f280	6	git-name-rev - Find symbolic names for given revs
bd321bcc JS	7
	8
	9	SYNOPSIS
	10	--------
e448ff87	11	[verse]
b1889c36	12	'git name-rev' [--tags] [--refs=<pattern>]
a8a5406a	13	( --all \| --stdin \| <commit-ish>... )
bd321bcc JS	14
	15	DESCRIPTION
	16	-----------
	17	Finds symbolic names suitable for human digestion for revisions given in any
0b444cdb	18	format parsable by 'git rev-parse'.
bd321bcc JS	19
	20
	21	OPTIONS
	22	-------
	23
	24	--tags::
	25	Do not use branch names, but only tags to name the commits
	26
2afc29aa	27	--refs=<pattern>::
98c5c4ad	28	Only use refs whose names match a given shell pattern. The pattern
290be667 JK	29	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.
2afc29aa	32
96415b49 JK	33	--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
bd321bcc JS	42	--all::
	43	List all commits reachable from all refs
	44
	45	--stdin::
3087b615 RR	46	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
	49	altogether. Intended for the scripter's use.
bd321bcc	50
23615708 SP	51	--name-only::
	52	Instead of printing both the SHA-1 and the name, print only
	53	the name. If given with --tags the usual tag prefix of
02783075	54	"tags/" is also omitted from the name, matching the output
372c7676	55	of `git-describe` more closely.
23615708	56
eba1351f SB	57	--no-undefined::
	58	Die with error code != 0 when a reference is undefined,
	59	instead of printing `undefined`.
	60
	61	--always::
	62	Show uniquely abbreviated commit object as fallback.
	63
76a8788c NTND	64	EXAMPLES
76a8788c NTND	65	--------
bd321bcc JS	66
bd321bcc JS	67	Given a commit, find out where it is relative to the local refs. Say somebody
2a75848e	68	wrote you about that fantastic commit 33db5f4d9027a10e477ccf054b2c1ab94f74c85a.
bd321bcc JS	69	Of course, you look into the commit, but that only tells you what happened, but
	70	not the context.
	71
0b444cdb	72	Enter 'git name-rev':
bd321bcc JS	73
	74	------------
	75	% git name-rev 33db5f4d9027a10e477ccf054b2c1ab94f74c85a
ee837244	76	33db5f4d9027a10e477ccf054b2c1ab94f74c85a tags/v0.99~940
bd321bcc JS	77	------------
	78
	79	Now you are wiser, because you know that it happened 940 revisions before v0.99.
	80
	81	Another nice thing you can do is:
	82
	83	------------
	84	% git log \| git name-rev --stdin
	85	------------
	86
bd321bcc JS	87	GIT
bd321bcc JS	88	---
9e1f0a85	89	Part of the linkgit:git[1] suite