]>
Commit | Line | Data |
---|---|---|
1 | git-describe(1) | |
2 | =============== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-describe - Give an object a human readable name based on an available ref | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...] | |
12 | 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] | |
13 | 'git describe' <blob> | |
14 | ||
15 | DESCRIPTION | |
16 | ----------- | |
17 | The command finds the most recent tag that is reachable from a | |
18 | commit. If the tag points to the commit, then only the tag is | |
19 | shown. Otherwise, it suffixes the tag name with the number of | |
20 | additional commits on top of the tagged object and the | |
21 | abbreviated object name of the most recent commit. The result | |
22 | is a "human-readable" object name which can also be used to | |
23 | identify the commit to other git commands. | |
24 | ||
25 | By default (without --all or --tags) `git describe` only shows | |
26 | annotated tags. For more information about creating annotated tags | |
27 | see the -a and -s options to linkgit:git-tag[1]. | |
28 | ||
29 | If the given object refers to a blob, it will be described | |
30 | as `<commit-ish>:<path>`, such that the blob can be found | |
31 | at `<path>` in the `<commit-ish>`, which itself describes the | |
32 | first commit in which this blob occurs in a reverse revision walk | |
33 | from HEAD. | |
34 | ||
35 | OPTIONS | |
36 | ------- | |
37 | <commit-ish>...:: | |
38 | Commit-ish object names to describe. Defaults to HEAD if omitted. | |
39 | ||
40 | --dirty[=<mark>]:: | |
41 | --broken[=<mark>]:: | |
42 | Describe the state of the working tree. When the working | |
43 | tree matches HEAD, the output is the same as "git describe | |
44 | HEAD". If the working tree has local modification "-dirty" | |
45 | is appended to it. If a repository is corrupt and Git | |
46 | cannot determine if there is local modification, Git will | |
47 | error out, unless `--broken' is given, which appends | |
48 | the suffix "-broken" instead. | |
49 | ||
50 | --all:: | |
51 | Instead of using only the annotated tags, use any ref | |
52 | found in `refs/` namespace. This option enables matching | |
53 | any known branch, remote-tracking branch, or lightweight tag. | |
54 | ||
55 | --tags:: | |
56 | Instead of using only the annotated tags, use any tag | |
57 | found in `refs/tags` namespace. This option enables matching | |
58 | a lightweight (non-annotated) tag. | |
59 | ||
60 | --contains:: | |
61 | Instead of finding the tag that predates the commit, find | |
62 | the tag that comes after the commit, and thus contains it. | |
63 | Automatically implies --tags. | |
64 | ||
65 | --abbrev=<n>:: | |
66 | Instead of using the default number of hexadecimal digits (which | |
67 | will vary according to the number of objects in the repository with | |
68 | a default of 7) of the abbreviated object name, use <n> digits, or | |
69 | as many digits as needed to form a unique object name. An <n> of 0 | |
70 | will suppress long format, only showing the closest tag. | |
71 | ||
72 | --candidates=<n>:: | |
73 | Instead of considering only the 10 most recent tags as | |
74 | candidates to describe the input commit-ish consider | |
75 | up to <n> candidates. Increasing <n> above 10 will take | |
76 | slightly longer but may produce a more accurate result. | |
77 | An <n> of 0 will cause only exact matches to be output. | |
78 | ||
79 | --exact-match:: | |
80 | Only output exact matches (a tag directly references the | |
81 | supplied commit). This is a synonym for --candidates=0. | |
82 | ||
83 | --debug:: | |
84 | Verbosely display information about the searching strategy | |
85 | being employed to standard error. The tag name will still | |
86 | be printed to standard out. | |
87 | ||
88 | --long:: | |
89 | Always output the long format (the tag, the number of commits | |
90 | and the abbreviated commit name) even when it matches a tag. | |
91 | This is useful when you want to see parts of the commit object name | |
92 | in "describe" output, even when the commit in question happens to be | |
93 | a tagged version. Instead of just emitting the tag name, it will | |
94 | describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2 | |
95 | that points at object deadbee....). | |
96 | ||
97 | --match <pattern>:: | |
98 | Only consider tags matching the given `glob(7)` pattern, | |
99 | excluding the "refs/tags/" prefix. If used with `--all`, it also | |
100 | considers local branches and remote-tracking references matching the | |
101 | pattern, excluding respectively "refs/heads/" and "refs/remotes/" | |
102 | prefix; references of other types are never considered. If given | |
103 | multiple times, a list of patterns will be accumulated, and tags | |
104 | matching any of the patterns will be considered. Use `--no-match` to | |
105 | clear and reset the list of patterns. | |
106 | ||
107 | --exclude <pattern>:: | |
108 | Do not consider tags matching the given `glob(7)` pattern, excluding | |
109 | the "refs/tags/" prefix. If used with `--all`, it also does not consider | |
110 | local branches and remote-tracking references matching the pattern, | |
111 | excluding respectively "refs/heads/" and "refs/remotes/" prefix; | |
112 | references of other types are never considered. If given multiple times, | |
113 | a list of patterns will be accumulated and tags matching any of the | |
114 | patterns will be excluded. When combined with --match a tag will be | |
115 | considered when it matches at least one --match pattern and does not | |
116 | match any of the --exclude patterns. Use `--no-exclude` to clear and | |
117 | reset the list of patterns. | |
118 | ||
119 | --always:: | |
120 | Show uniquely abbreviated commit object as fallback. | |
121 | ||
122 | --first-parent:: | |
123 | Follow only the first parent commit upon seeing a merge commit. | |
124 | This is useful when you wish to not match tags on branches merged | |
125 | in the history of the target commit. | |
126 | ||
127 | EXAMPLES | |
128 | -------- | |
129 | ||
130 | With something like git.git current tree, I get: | |
131 | ||
132 | [torvalds@g5 git]$ git describe parent | |
133 | v1.0.4-14-g2414721 | |
134 | ||
135 | i.e. the current head of my "parent" branch is based on v1.0.4, | |
136 | but since it has a few commits on top of that, | |
137 | describe has added the number of additional commits ("14") and | |
138 | an abbreviated object name for the commit itself ("2414721") | |
139 | at the end. | |
140 | ||
141 | The number of additional commits is the number | |
142 | of commits which would be displayed by "git log v1.0.4..parent". | |
143 | The hash suffix is "-g" + an unambiguous abbreviation for the tip commit | |
144 | of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The | |
145 | length of the abbreviation scales as the repository grows, using the | |
146 | approximate number of objects in the repository and a bit of math | |
147 | around the birthday paradox, and defaults to a minimum of 7. | |
148 | The "g" prefix stands for "git" and is used to allow describing the version of | |
149 | a software depending on the SCM the software is managed with. This is useful | |
150 | in an environment where people may use different SCMs. | |
151 | ||
152 | Doing a 'git describe' on a tag-name will just show the tag name: | |
153 | ||
154 | [torvalds@g5 git]$ git describe v1.0.4 | |
155 | v1.0.4 | |
156 | ||
157 | With --all, the command can use branch heads as references, so | |
158 | the output shows the reference path as well: | |
159 | ||
160 | [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2 | |
161 | tags/v1.0.0-21-g975b | |
162 | ||
163 | [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^ | |
164 | heads/lt/describe-7-g975b | |
165 | ||
166 | With --abbrev set to 0, the command can be used to find the | |
167 | closest tagname without any suffix: | |
168 | ||
169 | [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2 | |
170 | tags/v1.0.0 | |
171 | ||
172 | Note that the suffix you get if you type these commands today may be | |
173 | longer than what Linus saw above when he ran these commands, as your | |
174 | Git repository may have new commits whose object names begin with | |
175 | 975b that did not exist back then, and "-g975b" suffix alone may not | |
176 | be sufficient to disambiguate these commits. | |
177 | ||
178 | ||
179 | SEARCH STRATEGY | |
180 | --------------- | |
181 | ||
182 | For each commit-ish supplied, 'git describe' will first look for | |
183 | a tag which tags exactly that commit. Annotated tags will always | |
184 | be preferred over lightweight tags, and tags with newer dates will | |
185 | always be preferred over tags with older dates. If an exact match | |
186 | is found, its name will be output and searching will stop. | |
187 | ||
188 | If an exact match was not found, 'git describe' will walk back | |
189 | through the commit history to locate an ancestor commit which | |
190 | has been tagged. The ancestor's tag will be output along with an | |
191 | abbreviation of the input commit-ish's SHA-1. If `--first-parent` was | |
192 | specified then the walk will only consider the first parent of each | |
193 | commit. | |
194 | ||
195 | If multiple tags were found during the walk then the tag which | |
196 | has the fewest commits different from the input commit-ish will be | |
197 | selected and output. Here fewest commits different is defined as | |
198 | the number of commits which would be shown by `git log tag..input` | |
199 | will be the smallest number of commits possible. | |
200 | ||
201 | BUGS | |
202 | ---- | |
203 | ||
204 | Tree objects as well as tag objects not pointing at commits, cannot be described. | |
205 | When describing blobs, the lightweight tags pointing at blobs are ignored, | |
206 | but the blob is still described as <commit-ish>:<path> despite the lightweight | |
207 | tag being favorable. | |
208 | ||
209 | GIT | |
210 | --- | |
211 | Part of the linkgit:git[1] suite |