summaryrefslogtreecommitdiffstats
path: root/Documentation/git-name-rev.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-name-rev.txt')
-rw-r--r--Documentation/git-name-rev.txt112
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