34ae3b7071
Introduce a --annotate-stdin that is functionally equivalent of --stdin. --stdin does not behave as --stdin in other subcommands, such as pack-objects whereby it takes one argument per line. Since --stdin can be a confusing and misleading name, rename it to --annotate-stdin. This change adds a warning to --stdin warning that it will be removed in the future. Signed-off-by: "John Cai" <johncai86@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
116 lines
3.3 KiB
Plaintext
116 lines
3.3 KiB
Plaintext
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
|
|
|
|
--annotate-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.
|
|
+
|
|
For example:
|
|
+
|
|
-----------
|
|
$ 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
|
|
-----------
|
|
|
|
--stdin::
|
|
This option is deprecated in favor of 'git name-rev --annotate-stdin'.
|
|
They are functionally equivalent.
|
|
|
|
--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
|