blob: 74066bed0d94a9d4ca5d27f7a88e2209203aab7d [file] [log] [blame]
Junio C Hamanoab008762005-12-28 02:33:001<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamanoba4b9282008-07-06 05:20:316<meta name="generator" content="AsciiDoc 8.2.5" />
Junio C Hamanoab008762005-12-28 02:33:007<style type="text/css">
8/* Debug borders */
9p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
10/*
11 border: 1px solid red;
12*/
13}
14
15body {
16 margin: 1em 5% 1em 5%;
17}
18
Junio C Hamanoba4b9282008-07-06 05:20:3119a {
20 color: blue;
21 text-decoration: underline;
22}
23a:visited {
24 color: fuchsia;
25}
Junio C Hamanoab008762005-12-28 02:33:0026
27em {
28 font-style: italic;
29}
30
31strong {
32 font-weight: bold;
33}
34
35tt {
36 color: navy;
37}
38
39h1, h2, h3, h4, h5, h6 {
40 color: #527bbd;
41 font-family: sans-serif;
42 margin-top: 1.2em;
43 margin-bottom: 0.5em;
44 line-height: 1.3;
45}
46
Junio C Hamanoba4b9282008-07-06 05:20:3147h1, h2, h3 {
Junio C Hamanoab008762005-12-28 02:33:0048 border-bottom: 2px solid silver;
49}
50h2 {
Junio C Hamanoab008762005-12-28 02:33:0051 padding-top: 0.5em;
52}
Junio C Hamanoba4b9282008-07-06 05:20:3153h3 {
54 float: left;
55}
56h3 + * {
57 clear: left;
58}
Junio C Hamanoab008762005-12-28 02:33:0059
60div.sectionbody {
61 font-family: serif;
62 margin-left: 0;
63}
64
65hr {
66 border: 1px solid silver;
67}
68
69p {
70 margin-top: 0.5em;
71 margin-bottom: 0.5em;
72}
73
74pre {
75 padding: 0;
76 margin: 0;
77}
78
79span#author {
80 color: #527bbd;
81 font-family: sans-serif;
82 font-weight: bold;
Junio C Hamanoba4b9282008-07-06 05:20:3183 font-size: 1.1em;
Junio C Hamanoab008762005-12-28 02:33:0084}
85span#email {
86}
87span#revision {
88 font-family: sans-serif;
89}
90
91div#footer {
92 font-family: sans-serif;
93 font-size: small;
94 border-top: 2px solid silver;
95 padding-top: 0.5em;
96 margin-top: 4.0em;
97}
98div#footer-text {
99 float: left;
100 padding-bottom: 0.5em;
101}
102div#footer-badges {
103 float: right;
104 padding-bottom: 0.5em;
105}
106
107div#preamble,
108div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
109div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
110div.admonitionblock {
111 margin-right: 10%;
112 margin-top: 1.5em;
113 margin-bottom: 1.5em;
114}
115div.admonitionblock {
116 margin-top: 2.5em;
117 margin-bottom: 2.5em;
118}
119
120div.content { /* Block element content. */
121 padding: 0;
122}
123
124/* Block element titles. */
125div.title, caption.title {
126 font-family: sans-serif;
127 font-weight: bold;
128 text-align: left;
129 margin-top: 1.0em;
130 margin-bottom: 0.5em;
131}
132div.title + * {
133 margin-top: 0;
134}
135
136td div.title:first-child {
137 margin-top: 0.0em;
138}
139div.content div.title:first-child {
140 margin-top: 0.0em;
141}
142div.content + div.title {
143 margin-top: 0.0em;
144}
145
146div.sidebarblock > div.content {
147 background: #ffffee;
148 border: 1px solid silver;
149 padding: 0.5em;
150}
151
Junio C Hamanoba4b9282008-07-06 05:20:31152div.listingblock {
153 margin-right: 0%;
154}
Junio C Hamanoab008762005-12-28 02:33:00155div.listingblock > div.content {
156 border: 1px solid silver;
157 background: #f4f4f4;
158 padding: 0.5em;
159}
160
161div.quoteblock > div.content {
162 padding-left: 2.0em;
163}
Junio C Hamanoba4b9282008-07-06 05:20:31164
165div.attribution {
Junio C Hamanoab008762005-12-28 02:33:00166 text-align: right;
167}
Junio C Hamanoba4b9282008-07-06 05:20:31168div.verseblock + div.attribution {
169 text-align: left;
170}
Junio C Hamanoab008762005-12-28 02:33:00171
172div.admonitionblock .icon {
173 vertical-align: top;
174 font-size: 1.1em;
175 font-weight: bold;
176 text-decoration: underline;
177 color: #527bbd;
178 padding-right: 0.5em;
179}
180div.admonitionblock td.content {
181 padding-left: 0.5em;
182 border-left: 2px solid silver;
183}
184
185div.exampleblock > div.content {
186 border-left: 2px solid silver;
187 padding: 0.5em;
188}
189
190div.verseblock div.content {
191 white-space: pre;
192}
193
194div.imageblock div.content { padding-left: 0; }
195div.imageblock img { border: 1px solid silver; }
196span.image img { border-style: none; }
197
198dl {
199 margin-top: 0.8em;
200 margin-bottom: 0.8em;
201}
202dt {
203 margin-top: 0.5em;
204 margin-bottom: 0;
205 font-style: italic;
206}
207dd > *:first-child {
208 margin-top: 0;
209}
210
211ul, ol {
212 list-style-position: outside;
213}
Junio C Hamanoba4b9282008-07-06 05:20:31214div.olist2 ol {
Junio C Hamanoab008762005-12-28 02:33:00215 list-style-type: lower-alpha;
216}
217
218div.tableblock > table {
Junio C Hamanoba4b9282008-07-06 05:20:31219 border: 3px solid #527bbd;
Junio C Hamanoab008762005-12-28 02:33:00220}
221thead {
222 font-family: sans-serif;
223 font-weight: bold;
224}
225tfoot {
226 font-weight: bold;
227}
228
229div.hlist {
230 margin-top: 0.8em;
231 margin-bottom: 0.8em;
232}
Junio C Hamanoba4b9282008-07-06 05:20:31233div.hlist td {
234 padding-bottom: 5px;
235}
Junio C Hamanoab008762005-12-28 02:33:00236td.hlist1 {
237 vertical-align: top;
238 font-style: italic;
239 padding-right: 0.8em;
240}
241td.hlist2 {
242 vertical-align: top;
243}
244
245@media print {
246 div#footer-badges { display: none; }
247}
Junio C Hamanoba4b9282008-07-06 05:20:31248
249div#toctitle {
250 color: #527bbd;
251 font-family: sans-serif;
252 font-size: 1.1em;
253 font-weight: bold;
254 margin-top: 1.0em;
255 margin-bottom: 0.1em;
256}
257
258div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
259 margin-top: 0;
260 margin-bottom: 0;
261}
262div.toclevel2 {
263 margin-left: 2em;
264 font-size: 0.9em;
265}
266div.toclevel3 {
267 margin-left: 4em;
268 font-size: 0.9em;
269}
270div.toclevel4 {
271 margin-left: 6em;
272 font-size: 0.9em;
273}
274include1::./stylesheets/xhtml11-manpage.css[]
Junio C Hamanoab008762005-12-28 02:33:00275/* Workarounds for IE6's broken and incomplete CSS2. */
276
277div.sidebar-content {
278 background: #ffffee;
279 border: 1px solid silver;
280 padding: 0.5em;
281}
282div.sidebar-title, div.image-title {
283 font-family: sans-serif;
284 font-weight: bold;
285 margin-top: 0.0em;
286 margin-bottom: 0.5em;
287}
288
289div.listingblock div.content {
290 border: 1px solid silver;
291 background: #f4f4f4;
292 padding: 0.5em;
293}
294
295div.quoteblock-content {
296 padding-left: 2.0em;
297}
298
299div.exampleblock-content {
300 border-left: 2px solid silver;
301 padding-left: 0.5em;
302}
Junio C Hamanoba4b9282008-07-06 05:20:31303
304/* IE6 sets dynamically generated links as visited. */
305div#toc a:visited { color: blue; }
Junio C Hamanoab008762005-12-28 02:33:00306</style>
307<title>git-describe(1)</title>
308</head>
309<body>
310<div id="header">
311<h1>
312git-describe(1) Manual Page
313</h1>
314<h2>NAME</h2>
315<div class="sectionbody">
316<p>git-describe -
Junio C Hamano01078922006-03-10 00:31:47317 Show the most recent tag that is reachable from a commit
Junio C Hamanoab008762005-12-28 02:33:00318</p>
319</div>
320</div>
321<h2>SYNOPSIS</h2>
322<div class="sectionbody">
Junio C Hamano0ecfa0f2009-11-10 22:13:24323<div class="verseblock">
324<div class="content"><em>git describe</em> [--all] [--tags] [--contains] [--abbrev=&lt;n&gt;] &lt;committish&gt;&#8230;
325<em>git describe</em> [--all] [--tags] [--contains] [--abbrev=&lt;n&gt;] --dirty[=&lt;mark&gt;]</div></div>
Junio C Hamanoab008762005-12-28 02:33:00326</div>
Junio C Hamanoba4b9282008-07-06 05:20:31327<h2 id="_description">DESCRIPTION</h2>
Junio C Hamanoab008762005-12-28 02:33:00328<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31329<div class="para"><p>The command finds the most recent tag that is reachable from a
Junio C Hamano2fbcd212008-05-14 22:26:07330commit. If the tag points to the commit, then only the tag is
331shown. Otherwise, it suffixes the tag name with the number of
332additional commits on top of the tagged object and the
Junio C Hamanoba4b9282008-07-06 05:20:31333abbreviated object name of the most recent commit.</p></div>
Junio C Hamano7d06a8a2008-10-20 05:42:33334<div class="para"><p>By default (without --all or --tags) <tt>git describe</tt> only shows
335annotated tags. For more information about creating annotated tags
336see the -a and -s options to <a href="git-tag.html">git-tag(1)</a>.</p></div>
Junio C Hamanoab008762005-12-28 02:33:00337</div>
Junio C Hamanoba4b9282008-07-06 05:20:31338<h2 id="_options">OPTIONS</h2>
Junio C Hamanoab008762005-12-28 02:33:00339<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31340<div class="vlist"><dl>
Junio C Hamanoab008762005-12-28 02:33:00341<dt>
Junio C Hamano9e395072008-07-31 22:11:21342&lt;committish&gt;&#8230;
Junio C Hamanoab008762005-12-28 02:33:00343</dt>
344<dd>
345<p>
Junio C Hamano9e395072008-07-31 22:11:21346 Committish object names to describe.
Junio C Hamanoab008762005-12-28 02:33:00347</p>
348</dd>
349<dt>
Junio C Hamano446ed772009-11-10 22:02:20350--dirty[=&lt;mark&gt;]
351</dt>
352<dd>
353<p>
354 Describe the working tree.
355 It means describe HEAD and appends &lt;mark&gt; (<tt>-dirty</tt> by
356 default) if the working tree is dirty.
357</p>
358</dd>
359<dt>
Junio C Hamanoab008762005-12-28 02:33:00360--all
361</dt>
362<dd>
363<p>
364 Instead of using only the annotated tags, use any ref
Junio C Hamano7d06a8a2008-10-20 05:42:33365 found in <tt>.git/refs/</tt>. This option enables matching
366 any known branch, remote branch, or lightweight tag.
Junio C Hamanoab008762005-12-28 02:33:00367</p>
368</dd>
369<dt>
370--tags
371</dt>
372<dd>
373<p>
374 Instead of using only the annotated tags, use any tag
Junio C Hamano7d06a8a2008-10-20 05:42:33375 found in <tt>.git/refs/tags</tt>. This option enables matching
376 a lightweight (non-annotated) tag.
Junio C Hamanoab008762005-12-28 02:33:00377</p>
378</dd>
379<dt>
Junio C Hamano5e284b42007-05-22 07:23:37380--contains
381</dt>
382<dd>
383<p>
384 Instead of finding the tag that predates the commit, find
385 the tag that comes after the commit, and thus contains it.
386 Automatically implies --tags.
387</p>
388</dd>
389<dt>
Junio C Hamanoab008762005-12-28 02:33:00390--abbrev=&lt;n&gt;
391</dt>
392<dd>
393<p>
Junio C Hamano22bcc112009-01-24 08:05:18394 Instead of using the default 7 hexadecimal digits as the
Junio C Hamanoc21ab052009-10-31 04:03:55395 abbreviated object name, use &lt;n&gt; digits, or as many digits
396 as needed to form a unique object name. An &lt;n&gt; of 0
397 will suppress long format, only showing the closest tag.
Junio C Hamanoab008762005-12-28 02:33:00398</p>
399</dd>
Junio C Hamanoedd2b0a2007-01-15 06:12:45400<dt>
401--candidates=&lt;n&gt;
402</dt>
403<dd>
404<p>
405 Instead of considering only the 10 most recent tags as
406 candidates to describe the input committish consider
407 up to &lt;n&gt; candidates. Increasing &lt;n&gt; above 10 will take
408 slightly longer but may produce a more accurate result.
Junio C Hamano24bc09a2008-02-28 00:27:44409 An &lt;n&gt; of 0 will cause only exact matches to be output.
410</p>
411</dd>
412<dt>
413--exact-match
414</dt>
415<dd>
416<p>
417 Only output exact matches (a tag directly references the
418 supplied commit). This is a synonym for --candidates=0.
Junio C Hamanoedd2b0a2007-01-15 06:12:45419</p>
420</dd>
421<dt>
422--debug
423</dt>
424<dd>
425<p>
426 Verbosely display information about the searching strategy
427 being employed to standard error. The tag name will still
428 be printed to standard out.
429</p>
430</dd>
Junio C Hamano9c334152008-02-12 03:18:52431<dt>
Junio C Hamano4f1d8c42008-03-03 02:01:16432--long
433</dt>
434<dd>
435<p>
436 Always output the long format (the tag, the number of commits
437 and the abbreviated commit name) even when it matches a tag.
438 This is useful when you want to see parts of the commit object name
439 in "describe" output, even when the commit in question happens to be
440 a tagged version. Instead of just emitting the tag name, it will
Junio C Hamanoc21ab052009-10-31 04:03:55441 describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2
442 that points at object deadbee&#8230;.).
Junio C Hamano4f1d8c42008-03-03 02:01:16443</p>
444</dd>
445<dt>
Junio C Hamano9c334152008-02-12 03:18:52446--match &lt;pattern&gt;
447</dt>
448<dd>
449<p>
450 Only consider tags matching the given pattern (can be used to avoid
451 leaking private tags made from the repository).
452</p>
453</dd>
Junio C Hamanoeb415992008-06-08 22:49:47454<dt>
455--always
456</dt>
457<dd>
458<p>
459 Show uniquely abbreviated commit object as fallback.
460</p>
461</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31462</dl></div>
Junio C Hamanoab008762005-12-28 02:33:00463</div>
Junio C Hamanoba4b9282008-07-06 05:20:31464<h2 id="_examples">EXAMPLES</h2>
Junio C Hamanoab008762005-12-28 02:33:00465<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31466<div class="para"><p>With something like git.git current tree, I get:</p></div>
Junio C Hamanoab008762005-12-28 02:33:00467<div class="literalblock">
468<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38469<pre><tt>[torvalds@g5 git]$ git describe parent
Junio C Hamanoa890c4f2007-01-28 10:29:21470v1.0.4-14-g2414721</tt></pre>
Junio C Hamanoab008762005-12-28 02:33:00471</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31472<div class="para"><p>i.e. the current head of my "parent" branch is based on v1.0.4,
Junio C Hamano6efe3022009-01-13 16:47:56473but since it has a few commits on top of that,
Junio C Hamanoa890c4f2007-01-28 10:29:21474describe has added the number of additional commits ("14") and
475an abbreviated object name for the commit itself ("2414721")
Junio C Hamanoba4b9282008-07-06 05:20:31476at the end.</p></div>
477<div class="para"><p>The number of additional commits is the number
Junio C Hamanoa890c4f2007-01-28 10:29:21478of commits which would be displayed by "git log v1.0.4..parent".
479The hash suffix is "-g" + 7-char abbreviation for the tip commit
Junio C Hamanoba4b9282008-07-06 05:20:31480of parent (which was <tt>2414721b194453f058079d897d13c4e377f92dc6</tt>).</p></div>
Junio C Hamano1aa40d22010-01-21 17:46:43481<div class="para"><p>Doing a <em>git describe</em> on a tag-name will just show the tag name:</p></div>
Junio C Hamanoab008762005-12-28 02:33:00482<div class="literalblock">
483<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38484<pre><tt>[torvalds@g5 git]$ git describe v1.0.4
Junio C Hamanoab008762005-12-28 02:33:00485v1.0.4</tt></pre>
486</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31487<div class="para"><p>With --all, the command can use branch heads as references, so
488the output shows the reference path as well:</p></div>
Junio C Hamanoab008762005-12-28 02:33:00489<div class="literalblock">
490<div class="content">
491<pre><tt>[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
Junio C Hamanoa890c4f2007-01-28 10:29:21492tags/v1.0.0-21-g975b</tt></pre>
Junio C Hamanoab008762005-12-28 02:33:00493</div></div>
494<div class="literalblock">
495<div class="content">
Junio C Hamanoc21ab052009-10-31 04:03:55496<pre><tt>[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
Junio C Hamanoa890c4f2007-01-28 10:29:21497heads/lt/describe-7-g975b</tt></pre>
498</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31499<div class="para"><p>With --abbrev set to 0, the command can be used to find the
500closest tagname without any suffix:</p></div>
Junio C Hamanoa890c4f2007-01-28 10:29:21501<div class="literalblock">
502<div class="content">
503<pre><tt>[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
504tags/v1.0.0</tt></pre>
Junio C Hamanoab008762005-12-28 02:33:00505</div></div>
Junio C Hamanoc21ab052009-10-31 04:03:55506<div class="para"><p>Note that the suffix you get if you type these commands today may be
Junio C Hamanoa1f86332009-11-05 05:28:43507longer than what Linus saw above when he ran these commands, as your
Junio C Hamanoc21ab052009-10-31 04:03:55508git repository may have new commits whose object names begin with
509975b that did not exist back then, and "-g975b" suffix alone may not
510be sufficient to disambiguate these commits.</p></div>
Junio C Hamanoab008762005-12-28 02:33:00511</div>
Junio C Hamanoba4b9282008-07-06 05:20:31512<h2 id="_search_strategy">SEARCH STRATEGY</h2>
Junio C Hamanoedd2b0a2007-01-15 06:12:45513<div class="sectionbody">
Junio C Hamano1aa40d22010-01-21 17:46:43514<div class="para"><p>For each committish supplied, <em>git describe</em> will first look for
Junio C Hamanoedd2b0a2007-01-15 06:12:45515a tag which tags exactly that commit. Annotated tags will always
516be preferred over lightweight tags, and tags with newer dates will
517always be preferred over tags with older dates. If an exact match
Junio C Hamanoba4b9282008-07-06 05:20:31518is found, its name will be output and searching will stop.</p></div>
Junio C Hamano1aa40d22010-01-21 17:46:43519<div class="para"><p>If an exact match was not found, <em>git describe</em> will walk back
Junio C Hamanoedd2b0a2007-01-15 06:12:45520through the commit history to locate an ancestor commit which
521has been tagged. The ancestor's tag will be output along with an
Junio C Hamanoba4b9282008-07-06 05:20:31522abbreviation of the input committish's SHA1.</p></div>
523<div class="para"><p>If multiple tags were found during the walk then the tag which
Junio C Hamanoedd2b0a2007-01-15 06:12:45524has the fewest commits different from the input committish will be
525selected and output. Here fewest commits different is defined as
Junio C Hamanofce7c7e2008-07-02 03:06:38526the number of commits which would be shown by <tt>git log tag..input</tt>
Junio C Hamanoba4b9282008-07-06 05:20:31527will be the smallest number of commits possible.</p></div>
Junio C Hamanoedd2b0a2007-01-15 06:12:45528</div>
Junio C Hamanoba4b9282008-07-06 05:20:31529<h2 id="_author">Author</h2>
Junio C Hamanoab008762005-12-28 02:33:00530<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31531<div class="para"><p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt;, but somewhat
Junio C Hamano0868a302008-07-22 09:20:44532butchered by Junio C Hamano &lt;gitster@pobox.com&gt;. Later significantly
Junio C Hamanoba4b9282008-07-06 05:20:31533updated by Shawn Pearce &lt;spearce@spearce.org&gt;.</p></div>
Junio C Hamanoab008762005-12-28 02:33:00534</div>
Junio C Hamanoba4b9282008-07-06 05:20:31535<h2 id="_documentation">Documentation</h2>
Junio C Hamanoab008762005-12-28 02:33:00536<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31537<div class="para"><p>Documentation by David Greaves, Junio C Hamano and the git-list &lt;git@vger.kernel.org&gt;.</p></div>
Junio C Hamanoab008762005-12-28 02:33:00538</div>
Junio C Hamanoba4b9282008-07-06 05:20:31539<h2 id="_git">GIT</h2>
Junio C Hamanoab008762005-12-28 02:33:00540<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31541<div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamanoab008762005-12-28 02:33:00542</div>
543<div id="footer">
544<div id="footer-text">
Junio C Hamanodca34822010-02-13 01:02:52545Last updated 2010-02-13 00:59:39 UTC
Junio C Hamanoab008762005-12-28 02:33:00546</div>
547</div>
548</body>
549</html>