1 <!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">
5 <meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" />
6 <meta name=
"generator" content=
"AsciiDoc 8.2.5" />
7 <style type=
"text/css">
9 p
, li
, dt
, dd
, div
, pre
, h1
, h2
, h3
, h4
, h5
, h6
{
11 border: 1px solid red;
16 margin: 1em 5% 1em 5%;
21 text-decoration: underline
;
39 h1
, h2
, h3
, h4
, h5
, h6
{
41 font-family: sans-serif
;
48 border-bottom: 2px solid silver
;
66 border: 1px solid silver
;
81 font-family: sans-serif
;
88 font-family: sans-serif
;
92 font-family: sans-serif
;
94 border-top: 2px solid silver
;
100 padding-bottom: 0.5em;
104 padding-bottom: 0.5em;
108 div
.tableblock
, div
.imageblock
, div
.exampleblock
, div
.verseblock
,
109 div
.quoteblock
, div
.literalblock
, div
.listingblock
, div
.sidebarblock
,
110 div
.admonitionblock
{
113 margin-bottom: 1.5em;
115 div
.admonitionblock
{
117 margin-bottom: 2.5em;
120 div
.content
{ /* Block element content. */
124 /* Block element titles. */
125 div
.title
, caption
.title
{
126 font-family: sans-serif
;
130 margin-bottom: 0.5em;
136 td div
.title:first-child
{
139 div
.content div
.title:first-child
{
142 div
.content
+ div
.title
{
146 div
.sidebarblock
> div
.content
{
148 border: 1px solid silver
;
155 div
.listingblock
> div
.content
{
156 border: 1px solid silver
;
161 div
.quoteblock
> div
.content
{
168 div
.verseblock
+ div
.attribution
{
172 div
.admonitionblock
.icon
{
176 text-decoration: underline
;
178 padding-right: 0.5em;
180 div
.admonitionblock td
.content
{
182 border-left: 2px solid silver
;
185 div
.exampleblock
> div
.content
{
186 border-left: 2px solid silver
;
190 div
.verseblock div
.content
{
194 div
.imageblock div
.content
{ padding-left: 0; }
195 div
.imageblock img
{ border: 1px solid silver
; }
196 span
.image img
{ border-style: none
; }
200 margin-bottom: 0.8em;
212 list-style-position: outside
;
215 list-style-type: lower-alpha
;
218 div
.tableblock
> table
{
219 border: 3px solid
#527bbd;
222 font-family: sans-serif
;
231 margin-bottom: 0.8em;
239 padding-right: 0.8em;
246 div#footer-badges
{ display: none
; }
251 font-family: sans-serif
;
255 margin-bottom: 0.1em;
258 div
.toclevel1
, div
.toclevel2
, div
.toclevel3
, div
.toclevel4
{
274 include1::./stylesheets
/xhtml11-manpage
.css
[]
275 /* Workarounds for IE6's broken and incomplete CSS2. */
277 div
.sidebar-content
{
279 border: 1px solid silver
;
282 div
.sidebar-title
, div
.image-title
{
283 font-family: sans-serif
;
286 margin-bottom: 0.5em;
289 div
.listingblock div
.content
{
290 border: 1px solid silver
;
295 div
.quoteblock-content
{
299 div
.exampleblock-content
{
300 border-left: 2px solid silver
;
304 /* IE6 sets dynamically generated links as visited. */
305 div#toc
a:visited
{ color: blue
; }
307 <title>git-describe(
1)
</title>
312 git-describe(
1) Manual Page
315 <div class=
"sectionbody">
317 Show the most recent tag that is reachable from a commit
322 <div class=
"sectionbody">
323 <div class=
"verseblock">
324 <div class=
"content"><em>git describe
</em> [--all] [--tags] [--contains] [--abbrev=
<n
>]
<committish
>…
325 <em>git describe
</em> [--all] [--tags] [--contains] [--abbrev=
<n
>] --dirty[=
<mark
>]
</div></div>
327 <h2 id=
"_description">DESCRIPTION
</h2>
328 <div class=
"sectionbody">
329 <div class=
"para"><p>The command finds the most recent tag that is reachable from a
330 commit. If the tag points to the commit, then only the tag is
331 shown. Otherwise, it suffixes the tag name with the number of
332 additional commits on top of the tagged object and the
333 abbreviated object name of the most recent commit.
</p></div>
334 <div class=
"para"><p>By default (without --all or --tags)
<tt>git describe
</tt> only shows
335 annotated tags. For more information about creating annotated tags
336 see the -a and -s options to
<a href=
"git-tag.html">git-tag(
1)
</a>.
</p></div>
338 <h2 id=
"_options">OPTIONS
</h2>
339 <div class=
"sectionbody">
340 <div class=
"vlist"><dl>
342 <committish
>…
346 Committish object names to describe.
350 --dirty[=
<mark
>]
354 Describe the working tree.
355 It means describe HEAD and appends
<mark
> (
<tt>-dirty
</tt> by
356 default) if the working tree is dirty.
364 Instead of using only the annotated tags, use any ref
365 found in
<tt>.git/refs/
</tt>. This option enables matching
366 any known branch, remote branch, or lightweight tag.
374 Instead of using only the annotated tags, use any tag
375 found in
<tt>.git/refs/tags
</tt>. This option enables matching
376 a lightweight (non-annotated) tag.
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.
394 Instead of using the default
7 hexadecimal digits as the
395 abbreviated object name, use
<n
> digits, or as many digits
396 as needed to form a unique object name. An
<n
> of
0
397 will suppress long format, only showing the closest tag.
401 --candidates=
<n
>
405 Instead of considering only the
10 most recent tags as
406 candidates to describe the input committish consider
407 up to
<n
> candidates. Increasing
<n
> above
10 will take
408 slightly longer but may produce a more accurate result.
409 An
<n
> of
0 will cause only exact matches to be output.
417 Only output exact matches (a tag directly references the
418 supplied commit). This is a synonym for --candidates=
0.
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.
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
441 describe such a commit as v1.2-
0-gdeadbee (
0th commit since tag v1.2
442 that points at object deadbee
….).
446 --match
<pattern
>
450 Only consider tags matching the given pattern (can be used to avoid
451 leaking private tags made from the repository).
459 Show uniquely abbreviated commit object as fallback.
464 <h2 id=
"_examples">EXAMPLES
</h2>
465 <div class=
"sectionbody">
466 <div class=
"para"><p>With something like git.git current tree, I get:
</p></div>
467 <div class=
"literalblock">
468 <div class=
"content">
469 <pre><tt>[torvalds@g5 git]$ git describe parent
470 v1.0
.4-
14-g2414721
</tt></pre>
472 <div class=
"para"><p>i.e. the current head of my
"parent" branch is based on v1.0
.4,
473 but since it has a few commits on top of that,
474 describe has added the number of additional commits (
"14") and
475 an abbreviated object name for the commit itself (
"2414721")
476 at the end.
</p></div>
477 <div class=
"para"><p>The number of additional commits is the number
478 of commits which would be displayed by
"git log v1.0.4..parent".
479 The hash suffix is
"-g" +
7-char abbreviation for the tip commit
480 of parent (which was
<tt>2414721b194453f058079d897d13c4e377f92dc6
</tt>).
481 The
"g" prefix stands for
"git" and is used to allow describing the version of
482 a software depending on the SCM the software is managed with. This is useful
483 in an environment where people may use different SCMs.
</p></div>
484 <div class=
"para"><p>Doing a
<em>git describe
</em> on a tag-name will just show the tag name:
</p></div>
485 <div class=
"literalblock">
486 <div class=
"content">
487 <pre><tt>[torvalds@g5 git]$ git describe v1.0
.4
490 <div class=
"para"><p>With --all, the command can use branch heads as references, so
491 the output shows the reference path as well:
</p></div>
492 <div class=
"literalblock">
493 <div class=
"content">
494 <pre><tt>[torvalds@g5 git]$ git describe --all --abbrev=
4 v1.0
.5^
2
495 tags/v1.0
.0-
21-g975b
</tt></pre>
497 <div class=
"literalblock">
498 <div class=
"content">
499 <pre><tt>[torvalds@g5 git]$ git describe --all --abbrev=
4 HEAD^
500 heads/lt/describe-
7-g975b
</tt></pre>
502 <div class=
"para"><p>With --abbrev set to
0, the command can be used to find the
503 closest tagname without any suffix:
</p></div>
504 <div class=
"literalblock">
505 <div class=
"content">
506 <pre><tt>[torvalds@g5 git]$ git describe --abbrev=
0 v1.0
.5^
2
507 tags/v1.0
.0</tt></pre>
509 <div class=
"para"><p>Note that the suffix you get if you type these commands today may be
510 longer than what Linus saw above when he ran these commands, as your
511 git repository may have new commits whose object names begin with
512 975b that did not exist back then, and
"-g975b" suffix alone may not
513 be sufficient to disambiguate these commits.
</p></div>
515 <h2 id=
"_search_strategy">SEARCH STRATEGY
</h2>
516 <div class=
"sectionbody">
517 <div class=
"para"><p>For each committish supplied,
<em>git describe
</em> will first look for
518 a tag which tags exactly that commit. Annotated tags will always
519 be preferred over lightweight tags, and tags with newer dates will
520 always be preferred over tags with older dates. If an exact match
521 is found, its name will be output and searching will stop.
</p></div>
522 <div class=
"para"><p>If an exact match was not found,
<em>git describe
</em> will walk back
523 through the commit history to locate an ancestor commit which
524 has been tagged. The ancestor's tag will be output along with an
525 abbreviation of the input committish's SHA1.
</p></div>
526 <div class=
"para"><p>If multiple tags were found during the walk then the tag which
527 has the fewest commits different from the input committish will be
528 selected and output. Here fewest commits different is defined as
529 the number of commits which would be shown by
<tt>git log tag..input
</tt>
530 will be the smallest number of commits possible.
</p></div>
532 <h2 id=
"_author">Author
</h2>
533 <div class=
"sectionbody">
534 <div class=
"para"><p>Written by Linus Torvalds
<torvalds@osdl.org
>, but somewhat
535 butchered by Junio C Hamano
<gitster@pobox.com
>. Later significantly
536 updated by Shawn Pearce
<spearce@spearce.org
>.
</p></div>
538 <h2 id=
"_documentation">Documentation
</h2>
539 <div class=
"sectionbody">
540 <div class=
"para"><p>Documentation by David Greaves, Junio C Hamano and the git-list
<git@vger.kernel.org
>.
</p></div>
542 <h2 id=
"_git">GIT
</h2>
543 <div class=
"sectionbody">
544 <div class=
"para"><p>Part of the
<a href=
"git.html">git(
1)
</a> suite
</p></div>
547 <div id=
"footer-text">
548 Last updated
2010-
03-
25 00:
38:
20 UTC