blob: 978fb4e7acfcd7101690d621bfbe8de66c7bb36a [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 Hamanoba4b9282008-07-06 05:20:31323<div class="para"><p><em>git describe</em> [--all] [--tags] [--contains] [--abbrev=&lt;n&gt;] &lt;committish&gt;&#8230;</p></div>
Junio C Hamanoab008762005-12-28 02:33:00324</div>
Junio C Hamanoba4b9282008-07-06 05:20:31325<h2 id="_description">DESCRIPTION</h2>
Junio C Hamanoab008762005-12-28 02:33:00326<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31327<div class="para"><p>The command finds the most recent tag that is reachable from a
Junio C Hamano2fbcd212008-05-14 22:26:07328commit. If the tag points to the commit, then only the tag is
329shown. Otherwise, it suffixes the tag name with the number of
330additional commits on top of the tagged object and the
Junio C Hamanoba4b9282008-07-06 05:20:31331abbreviated object name of the most recent commit.</p></div>
Junio C Hamano7d06a8a2008-10-20 05:42:33332<div class="para"><p>By default (without --all or --tags) <tt>git describe</tt> only shows
333annotated tags. For more information about creating annotated tags
334see the -a and -s options to <a href="git-tag.html">git-tag(1)</a>.</p></div>
Junio C Hamanoab008762005-12-28 02:33:00335</div>
Junio C Hamanoba4b9282008-07-06 05:20:31336<h2 id="_options">OPTIONS</h2>
Junio C Hamanoab008762005-12-28 02:33:00337<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31338<div class="vlist"><dl>
Junio C Hamanoab008762005-12-28 02:33:00339<dt>
Junio C Hamano9e395072008-07-31 22:11:21340&lt;committish&gt;&#8230;
Junio C Hamanoab008762005-12-28 02:33:00341</dt>
342<dd>
343<p>
Junio C Hamano9e395072008-07-31 22:11:21344 Committish object names to describe.
Junio C Hamanoab008762005-12-28 02:33:00345</p>
346</dd>
347<dt>
348--all
349</dt>
350<dd>
351<p>
352 Instead of using only the annotated tags, use any ref
Junio C Hamano7d06a8a2008-10-20 05:42:33353 found in <tt>.git/refs/</tt>. This option enables matching
354 any known branch, remote branch, or lightweight tag.
Junio C Hamanoab008762005-12-28 02:33:00355</p>
356</dd>
357<dt>
358--tags
359</dt>
360<dd>
361<p>
362 Instead of using only the annotated tags, use any tag
Junio C Hamano7d06a8a2008-10-20 05:42:33363 found in <tt>.git/refs/tags</tt>. This option enables matching
364 a lightweight (non-annotated) tag.
Junio C Hamanoab008762005-12-28 02:33:00365</p>
366</dd>
367<dt>
Junio C Hamano5e284b42007-05-22 07:23:37368--contains
369</dt>
370<dd>
371<p>
372 Instead of finding the tag that predates the commit, find
373 the tag that comes after the commit, and thus contains it.
374 Automatically implies --tags.
375</p>
376</dd>
377<dt>
Junio C Hamanoab008762005-12-28 02:33:00378--abbrev=&lt;n&gt;
379</dt>
380<dd>
381<p>
Junio C Hamano22bcc112009-01-24 08:05:18382 Instead of using the default 7 hexadecimal digits as the
Junio C Hamanoc21ab052009-10-31 04:03:55383 abbreviated object name, use &lt;n&gt; digits, or as many digits
384 as needed to form a unique object name. An &lt;n&gt; of 0
385 will suppress long format, only showing the closest tag.
Junio C Hamanoab008762005-12-28 02:33:00386</p>
387</dd>
Junio C Hamanoedd2b0a2007-01-15 06:12:45388<dt>
389--candidates=&lt;n&gt;
390</dt>
391<dd>
392<p>
393 Instead of considering only the 10 most recent tags as
394 candidates to describe the input committish consider
395 up to &lt;n&gt; candidates. Increasing &lt;n&gt; above 10 will take
396 slightly longer but may produce a more accurate result.
Junio C Hamano24bc09a2008-02-28 00:27:44397 An &lt;n&gt; of 0 will cause only exact matches to be output.
398</p>
399</dd>
400<dt>
401--exact-match
402</dt>
403<dd>
404<p>
405 Only output exact matches (a tag directly references the
406 supplied commit). This is a synonym for --candidates=0.
Junio C Hamanoedd2b0a2007-01-15 06:12:45407</p>
408</dd>
409<dt>
410--debug
411</dt>
412<dd>
413<p>
414 Verbosely display information about the searching strategy
415 being employed to standard error. The tag name will still
416 be printed to standard out.
417</p>
418</dd>
Junio C Hamano9c334152008-02-12 03:18:52419<dt>
Junio C Hamano4f1d8c42008-03-03 02:01:16420--long
421</dt>
422<dd>
423<p>
424 Always output the long format (the tag, the number of commits
425 and the abbreviated commit name) even when it matches a tag.
426 This is useful when you want to see parts of the commit object name
427 in "describe" output, even when the commit in question happens to be
428 a tagged version. Instead of just emitting the tag name, it will
Junio C Hamanoc21ab052009-10-31 04:03:55429 describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2
430 that points at object deadbee&#8230;.).
Junio C Hamano4f1d8c42008-03-03 02:01:16431</p>
432</dd>
433<dt>
Junio C Hamano9c334152008-02-12 03:18:52434--match &lt;pattern&gt;
435</dt>
436<dd>
437<p>
438 Only consider tags matching the given pattern (can be used to avoid
439 leaking private tags made from the repository).
440</p>
441</dd>
Junio C Hamanoeb415992008-06-08 22:49:47442<dt>
443--always
444</dt>
445<dd>
446<p>
447 Show uniquely abbreviated commit object as fallback.
448</p>
449</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31450</dl></div>
Junio C Hamanoab008762005-12-28 02:33:00451</div>
Junio C Hamanoba4b9282008-07-06 05:20:31452<h2 id="_examples">EXAMPLES</h2>
Junio C Hamanoab008762005-12-28 02:33:00453<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31454<div class="para"><p>With something like git.git current tree, I get:</p></div>
Junio C Hamanoab008762005-12-28 02:33:00455<div class="literalblock">
456<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38457<pre><tt>[torvalds@g5 git]$ git describe parent
Junio C Hamanoa890c4f2007-01-28 10:29:21458v1.0.4-14-g2414721</tt></pre>
Junio C Hamanoab008762005-12-28 02:33:00459</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31460<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:56461but since it has a few commits on top of that,
Junio C Hamanoa890c4f2007-01-28 10:29:21462describe has added the number of additional commits ("14") and
463an abbreviated object name for the commit itself ("2414721")
Junio C Hamanoba4b9282008-07-06 05:20:31464at the end.</p></div>
465<div class="para"><p>The number of additional commits is the number
Junio C Hamanoa890c4f2007-01-28 10:29:21466of commits which would be displayed by "git log v1.0.4..parent".
467The hash suffix is "-g" + 7-char abbreviation for the tip commit
Junio C Hamanoba4b9282008-07-06 05:20:31468of parent (which was <tt>2414721b194453f058079d897d13c4e377f92dc6</tt>).</p></div>
469<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:00470<div class="literalblock">
471<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38472<pre><tt>[torvalds@g5 git]$ git describe v1.0.4
Junio C Hamanoab008762005-12-28 02:33:00473v1.0.4</tt></pre>
474</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31475<div class="para"><p>With --all, the command can use branch heads as references, so
476the output shows the reference path as well:</p></div>
Junio C Hamanoab008762005-12-28 02:33:00477<div class="literalblock">
478<div class="content">
479<pre><tt>[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
Junio C Hamanoa890c4f2007-01-28 10:29:21480tags/v1.0.0-21-g975b</tt></pre>
Junio C Hamanoab008762005-12-28 02:33:00481</div></div>
482<div class="literalblock">
483<div class="content">
Junio C Hamanoc21ab052009-10-31 04:03:55484<pre><tt>[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
Junio C Hamanoa890c4f2007-01-28 10:29:21485heads/lt/describe-7-g975b</tt></pre>
486</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31487<div class="para"><p>With --abbrev set to 0, the command can be used to find the
488closest tagname without any suffix:</p></div>
Junio C Hamanoa890c4f2007-01-28 10:29:21489<div class="literalblock">
490<div class="content">
491<pre><tt>[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
492tags/v1.0.0</tt></pre>
Junio C Hamanoab008762005-12-28 02:33:00493</div></div>
Junio C Hamanoc21ab052009-10-31 04:03:55494<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:43495longer than what Linus saw above when he ran these commands, as your
Junio C Hamanoc21ab052009-10-31 04:03:55496git repository may have new commits whose object names begin with
497975b that did not exist back then, and "-g975b" suffix alone may not
498be sufficient to disambiguate these commits.</p></div>
Junio C Hamanoab008762005-12-28 02:33:00499</div>
Junio C Hamanoba4b9282008-07-06 05:20:31500<h2 id="_search_strategy">SEARCH STRATEGY</h2>
Junio C Hamanoedd2b0a2007-01-15 06:12:45501<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31502<div class="para"><p>For each committish supplied, <em>git-describe</em> will first look for
Junio C Hamanoedd2b0a2007-01-15 06:12:45503a tag which tags exactly that commit. Annotated tags will always
504be preferred over lightweight tags, and tags with newer dates will
505always be preferred over tags with older dates. If an exact match
Junio C Hamanoba4b9282008-07-06 05:20:31506is found, its name will be output and searching will stop.</p></div>
507<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:45508through the commit history to locate an ancestor commit which
509has been tagged. The ancestor's tag will be output along with an
Junio C Hamanoba4b9282008-07-06 05:20:31510abbreviation of the input committish's SHA1.</p></div>
511<div class="para"><p>If multiple tags were found during the walk then the tag which
Junio C Hamanoedd2b0a2007-01-15 06:12:45512has the fewest commits different from the input committish will be
513selected and output. Here fewest commits different is defined as
Junio C Hamanofce7c7e2008-07-02 03:06:38514the number of commits which would be shown by <tt>git log tag..input</tt>
Junio C Hamanoba4b9282008-07-06 05:20:31515will be the smallest number of commits possible.</p></div>
Junio C Hamanoedd2b0a2007-01-15 06:12:45516</div>
Junio C Hamanoba4b9282008-07-06 05:20:31517<h2 id="_author">Author</h2>
Junio C Hamanoab008762005-12-28 02:33:00518<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31519<div class="para"><p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt;, but somewhat
Junio C Hamano0868a302008-07-22 09:20:44520butchered by Junio C Hamano &lt;gitster@pobox.com&gt;. Later significantly
Junio C Hamanoba4b9282008-07-06 05:20:31521updated by Shawn Pearce &lt;spearce@spearce.org&gt;.</p></div>
Junio C Hamanoab008762005-12-28 02:33:00522</div>
Junio C Hamanoba4b9282008-07-06 05:20:31523<h2 id="_documentation">Documentation</h2>
Junio C Hamanoab008762005-12-28 02:33:00524<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31525<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:00526</div>
Junio C Hamanoba4b9282008-07-06 05:20:31527<h2 id="_git">GIT</h2>
Junio C Hamanoab008762005-12-28 02:33:00528<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31529<div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamanoab008762005-12-28 02:33:00530</div>
531<div id="footer">
532<div id="footer-text">
Junio C Hamanoa1f86332009-11-05 05:28:43533Last updated 2009-11-05 05:28:28 UTC
Junio C Hamanoab008762005-12-28 02:33:00534</div>
535</div>
536</body>
537</html>