diff options
Diffstat (limited to 'Documentation/git-name-rev.txt')
| -rw-r--r-- | Documentation/git-name-rev.txt | 112 |
1 files changed, 112 insertions, 0 deletions
diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt new file mode 100644 index 0000000..d4f1c4d --- /dev/null +++ b/Documentation/git-name-rev.txt @@ -0,0 +1,112 @@ +git-name-rev(1) +=============== + +NAME +---- +git-name-rev - Find symbolic names for given revs + + +SYNOPSIS +-------- +[verse] +'git name-rev' [--tags] [--refs=<pattern>] + ( --all | --annotate-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 a branch name, a tag name, or a 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. This option was called `--stdin` in older versions + of Git. ++ +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 +----------- + +--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 --annotate-stdin +------------ + +GIT +--- +Part of the linkgit:git[1] suite |