| 1 | git-name-rev(1) |
| 2 | =============== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-name-rev - Find symbolic names for given revs |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [verse] |
| 12 | 'git name-rev' [--tags] [--refs=<pattern>] |
| 13 | ( --all | --annotate-stdin | <commit-ish>... ) |
| 14 | |
| 15 | DESCRIPTION |
| 16 | ----------- |
| 17 | Finds symbolic names suitable for human digestion for revisions given in any |
| 18 | format parsable by 'git rev-parse'. |
| 19 | |
| 20 | |
| 21 | OPTIONS |
| 22 | ------- |
| 23 | |
| 24 | --tags:: |
| 25 | Do not use branch names, but only tags to name the commits |
| 26 | |
| 27 | --refs=<pattern>:: |
| 28 | Only use refs whose names match a given shell pattern. The pattern |
| 29 | can be a branch name, a tag name, or a 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. |
| 32 | |
| 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 | |
| 42 | --all:: |
| 43 | List all commits reachable from all refs |
| 44 | |
| 45 | --annotate-stdin:: |
| 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. This option was called `--stdin` in older versions |
| 50 | of Git. |
| 51 | + |
| 52 | For example: |
| 53 | + |
| 54 | ----------- |
| 55 | $ cat sample.txt |
| 56 | |
| 57 | An abbreviated revision 2ae0a9cb82 will not be substituted. |
| 58 | The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907, |
| 59 | while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad |
| 60 | |
| 61 | $ git name-rev --annotate-stdin <sample.txt |
| 62 | |
| 63 | An abbreviated revision 2ae0a9cb82 will not be substituted. |
| 64 | The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907 (master), |
| 65 | while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad |
| 66 | |
| 67 | $ git name-rev --name-only --annotate-stdin <sample.txt |
| 68 | |
| 69 | An abbreviated revision 2ae0a9cb82 will not be substituted. |
| 70 | The full name after substitution is master, |
| 71 | while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad |
| 72 | ----------- |
| 73 | |
| 74 | --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 |
| 77 | "tags/" is also omitted from the name, matching the output |
| 78 | of `git-describe` more closely. |
| 79 | |
| 80 | --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 | |
| 87 | EXAMPLES |
| 88 | -------- |
| 89 | |
| 90 | Given a commit, find out where it is relative to the local refs. Say somebody |
| 91 | wrote you about that fantastic commit 33db5f4d9027a10e477ccf054b2c1ab94f74c85a. |
| 92 | Of course, you look into the commit, but that only tells you what happened, but |
| 93 | not the context. |
| 94 | |
| 95 | Enter 'git name-rev': |
| 96 | |
| 97 | ------------ |
| 98 | % git name-rev 33db5f4d9027a10e477ccf054b2c1ab94f74c85a |
| 99 | 33db5f4d9027a10e477ccf054b2c1ab94f74c85a tags/v0.99~940 |
| 100 | ------------ |
| 101 | |
| 102 | Now you are wiser, because you know that it happened 940 revisions before v0.99. |
| 103 | |
| 104 | Another nice thing you can do is: |
| 105 | |
| 106 | ------------ |
| 107 | % git log | git name-rev --annotate-stdin |
| 108 | ------------ |
| 109 | |
| 110 | GIT |
| 111 | --- |
| 112 | Part of the linkgit:git[1] suite |