<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" | |
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> | |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> | |
<head> | |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> | |
<meta name="generator" content="AsciiDoc 7.0.2" /> | |
<style type="text/css"> | |
/* Debug borders */ | |
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { | |
/* | |
border: 1px solid red; | |
*/ | |
} | |
body { | |
margin: 1em 5% 1em 5%; | |
} | |
a { color: blue; } | |
a:visited { color: fuchsia; } | |
em { | |
font-style: italic; | |
} | |
strong { | |
font-weight: bold; | |
} | |
tt { | |
color: navy; | |
} | |
h1, h2, h3, h4, h5, h6 { | |
color: #527bbd; | |
font-family: sans-serif; | |
margin-top: 1.2em; | |
margin-bottom: 0.5em; | |
line-height: 1.3; | |
} | |
h1 { | |
border-bottom: 2px solid silver; | |
} | |
h2 { | |
border-bottom: 2px solid silver; | |
padding-top: 0.5em; | |
} | |
div.sectionbody { | |
font-family: serif; | |
margin-left: 0; | |
} | |
hr { | |
border: 1px solid silver; | |
} | |
p { | |
margin-top: 0.5em; | |
margin-bottom: 0.5em; | |
} | |
pre { | |
padding: 0; | |
margin: 0; | |
} | |
span#author { | |
color: #527bbd; | |
font-family: sans-serif; | |
font-weight: bold; | |
font-size: 1.2em; | |
} | |
span#email { | |
} | |
span#revision { | |
font-family: sans-serif; | |
} | |
div#footer { | |
font-family: sans-serif; | |
font-size: small; | |
border-top: 2px solid silver; | |
padding-top: 0.5em; | |
margin-top: 4.0em; | |
} | |
div#footer-text { | |
float: left; | |
padding-bottom: 0.5em; | |
} | |
div#footer-badges { | |
float: right; | |
padding-bottom: 0.5em; | |
} | |
div#preamble, | |
div.tableblock, div.imageblock, div.exampleblock, div.verseblock, | |
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, | |
div.admonitionblock { | |
margin-right: 10%; | |
margin-top: 1.5em; | |
margin-bottom: 1.5em; | |
} | |
div.admonitionblock { | |
margin-top: 2.5em; | |
margin-bottom: 2.5em; | |
} | |
div.content { /* Block element content. */ | |
padding: 0; | |
} | |
/* Block element titles. */ | |
div.title, caption.title { | |
font-family: sans-serif; | |
font-weight: bold; | |
text-align: left; | |
margin-top: 1.0em; | |
margin-bottom: 0.5em; | |
} | |
div.title + * { | |
margin-top: 0; | |
} | |
td div.title:first-child { | |
margin-top: 0.0em; | |
} | |
div.content div.title:first-child { | |
margin-top: 0.0em; | |
} | |
div.content + div.title { | |
margin-top: 0.0em; | |
} | |
div.sidebarblock > div.content { | |
background: #ffffee; | |
border: 1px solid silver; | |
padding: 0.5em; | |
} | |
div.listingblock > div.content { | |
border: 1px solid silver; | |
background: #f4f4f4; | |
padding: 0.5em; | |
} | |
div.quoteblock > div.content { | |
padding-left: 2.0em; | |
} | |
div.quoteblock .attribution { | |
text-align: right; | |
} | |
div.admonitionblock .icon { | |
vertical-align: top; | |
font-size: 1.1em; | |
font-weight: bold; | |
text-decoration: underline; | |
color: #527bbd; | |
padding-right: 0.5em; | |
} | |
div.admonitionblock td.content { | |
padding-left: 0.5em; | |
border-left: 2px solid silver; | |
} | |
div.exampleblock > div.content { | |
border-left: 2px solid silver; | |
padding: 0.5em; | |
} | |
div.verseblock div.content { | |
white-space: pre; | |
} | |
div.imageblock div.content { padding-left: 0; } | |
div.imageblock img { border: 1px solid silver; } | |
span.image img { border-style: none; } | |
dl { | |
margin-top: 0.8em; | |
margin-bottom: 0.8em; | |
} | |
dt { | |
margin-top: 0.5em; | |
margin-bottom: 0; | |
font-style: italic; | |
} | |
dd > *:first-child { | |
margin-top: 0; | |
} | |
ul, ol { | |
list-style-position: outside; | |
} | |
ol.olist2 { | |
list-style-type: lower-alpha; | |
} | |
div.tableblock > table { | |
border-color: #527bbd; | |
border-width: 3px; | |
} | |
thead { | |
font-family: sans-serif; | |
font-weight: bold; | |
} | |
tfoot { | |
font-weight: bold; | |
} | |
div.hlist { | |
margin-top: 0.8em; | |
margin-bottom: 0.8em; | |
} | |
td.hlist1 { | |
vertical-align: top; | |
font-style: italic; | |
padding-right: 0.8em; | |
} | |
td.hlist2 { | |
vertical-align: top; | |
} | |
@media print { | |
div#footer-badges { display: none; } | |
} | |
include::./stylesheets/xhtml11-manpage.css[] | |
/* Workarounds for IE6's broken and incomplete CSS2. */ | |
div.sidebar-content { | |
background: #ffffee; | |
border: 1px solid silver; | |
padding: 0.5em; | |
} | |
div.sidebar-title, div.image-title { | |
font-family: sans-serif; | |
font-weight: bold; | |
margin-top: 0.0em; | |
margin-bottom: 0.5em; | |
} | |
div.listingblock div.content { | |
border: 1px solid silver; | |
background: #f4f4f4; | |
padding: 0.5em; | |
} | |
div.quoteblock-content { | |
padding-left: 2.0em; | |
} | |
div.exampleblock-content { | |
border-left: 2px solid silver; | |
padding-left: 0.5em; | |
} | |
</style> | |
<title>git-describe(1)</title> | |
</head> | |
<body> | |
<div id="header"> | |
<h1> | |
git-describe(1) Manual Page | |
</h1> | |
<h2>NAME</h2> | |
<div class="sectionbody"> | |
<p>git-describe - | |
Show the most recent tag that is reachable from a commit | |
</p> | |
</div> | |
</div> | |
<h2>SYNOPSIS</h2> | |
<div class="sectionbody"> | |
<p><em>git-describe</em> [--all] [--tags] [--contains] [--abbrev=<n>] <committish>…</p> | |
</div> | |
<h2>DESCRIPTION</h2> | |
<div class="sectionbody"> | |
<p>The command finds the most recent tag that is reachable from a | |
commit. If the tag points to the commit, then only the tag is | |
shown. Otherwise, it suffixes the tag name with the number of | |
additional commits on top of the tagged object and the | |
abbreviated object name of the most recent commit.</p> | |
</div> | |
<h2>OPTIONS</h2> | |
<div class="sectionbody"> | |
<dl> | |
<dt> | |
<committish> | |
</dt> | |
<dd> | |
<p> | |
The object name of the committish. | |
</p> | |
</dd> | |
<dt> | |
--all | |
</dt> | |
<dd> | |
<p> | |
Instead of using only the annotated tags, use any ref | |
found in <tt>.git/refs/</tt>. | |
</p> | |
</dd> | |
<dt> | |
--tags | |
</dt> | |
<dd> | |
<p> | |
Instead of using only the annotated tags, use any tag | |
found in <tt>.git/refs/tags</tt>. | |
</p> | |
</dd> | |
<dt> | |
--contains | |
</dt> | |
<dd> | |
<p> | |
Instead of finding the tag that predates the commit, find | |
the tag that comes after the commit, and thus contains it. | |
Automatically implies --tags. | |
</p> | |
</dd> | |
<dt> | |
--abbrev=<n> | |
</dt> | |
<dd> | |
<p> | |
Instead of using the default 8 hexadecimal digits as the | |
abbreviated object name, use <n> digits. | |
</p> | |
</dd> | |
<dt> | |
--candidates=<n> | |
</dt> | |
<dd> | |
<p> | |
Instead of considering only the 10 most recent tags as | |
candidates to describe the input committish consider | |
up to <n> candidates. Increasing <n> above 10 will take | |
slightly longer but may produce a more accurate result. | |
An <n> of 0 will cause only exact matches to be output. | |
</p> | |
</dd> | |
<dt> | |
--exact-match | |
</dt> | |
<dd> | |
<p> | |
Only output exact matches (a tag directly references the | |
supplied commit). This is a synonym for --candidates=0. | |
</p> | |
</dd> | |
<dt> | |
--debug | |
</dt> | |
<dd> | |
<p> | |
Verbosely display information about the searching strategy | |
being employed to standard error. The tag name will still | |
be printed to standard out. | |
</p> | |
</dd> | |
<dt> | |
--long | |
</dt> | |
<dd> | |
<p> | |
Always output the long format (the tag, the number of commits | |
and the abbreviated commit name) even when it matches a tag. | |
This is useful when you want to see parts of the commit object name | |
in "describe" output, even when the commit in question happens to be | |
a tagged version. Instead of just emitting the tag name, it will | |
describe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2 | |
that points at object deadbeef….). | |
</p> | |
</dd> | |
<dt> | |
--match <pattern> | |
</dt> | |
<dd> | |
<p> | |
Only consider tags matching the given pattern (can be used to avoid | |
leaking private tags made from the repository). | |
</p> | |
</dd> | |
<dt> | |
--always | |
</dt> | |
<dd> | |
<p> | |
Show uniquely abbreviated commit object as fallback. | |
</p> | |
</dd> | |
</dl> | |
</div> | |
<h2>EXAMPLES</h2> | |
<div class="sectionbody"> | |
<p>With something like git.git current tree, I get:</p> | |
<div class="literalblock"> | |
<div class="content"> | |
<pre><tt>[torvalds@g5 git]$ git-describe parent | |
v1.0.4-14-g2414721</tt></pre> | |
</div></div> | |
<p>i.e. the current head of my "parent" branch is based on v1.0.4, | |
but since it has a handful commits on top of that, | |
describe has added the number of additional commits ("14") and | |
an abbreviated object name for the commit itself ("2414721") | |
at the end.</p> | |
<p>The number of additional commits is the number | |
of commits which would be displayed by "git log v1.0.4..parent". | |
The hash suffix is "-g" + 7-char abbreviation for the tip commit | |
of parent (which was <tt>2414721b194453f058079d897d13c4e377f92dc6</tt>).</p> | |
<p>Doing a "git-describe" on a tag-name will just show the tag name:</p> | |
<div class="literalblock"> | |
<div class="content"> | |
<pre><tt>[torvalds@g5 git]$ git-describe v1.0.4 | |
v1.0.4</tt></pre> | |
</div></div> | |
<p>With --all, the command can use branch heads as references, so | |
the output shows the reference path as well:</p> | |
<div class="literalblock"> | |
<div class="content"> | |
<pre><tt>[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2 | |
tags/v1.0.0-21-g975b</tt></pre> | |
</div></div> | |
<div class="literalblock"> | |
<div class="content"> | |
<pre><tt>[torvalds@g5 git]$ git describe --all HEAD^ | |
heads/lt/describe-7-g975b</tt></pre> | |
</div></div> | |
<p>With --abbrev set to 0, the command can be used to find the | |
closest tagname without any suffix:</p> | |
<div class="literalblock"> | |
<div class="content"> | |
<pre><tt>[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2 | |
tags/v1.0.0</tt></pre> | |
</div></div> | |
</div> | |
<h2>SEARCH STRATEGY</h2> | |
<div class="sectionbody"> | |
<p>For each committish supplied "git describe" will first look for | |
a tag which tags exactly that commit. Annotated tags will always | |
be preferred over lightweight tags, and tags with newer dates will | |
always be preferred over tags with older dates. If an exact match | |
is found, its name will be output and searching will stop.</p> | |
<p>If an exact match was not found "git describe" will walk back | |
through the commit history to locate an ancestor commit which | |
has been tagged. The ancestor's tag will be output along with an | |
abbreviation of the input committish's SHA1.</p> | |
<p>If multiple tags were found during the walk then the tag which | |
has the fewest commits different from the input committish will be | |
selected and output. Here fewest commits different is defined as | |
the number of commits which would be shown by "git log tag..input" | |
will be the smallest number of commits possible.</p> | |
</div> | |
<h2>Author</h2> | |
<div class="sectionbody"> | |
<p>Written by Linus Torvalds <torvalds@osdl.org>, but somewhat | |
butchered by Junio C Hamano <junkio@cox.net>. Later significantly | |
updated by Shawn Pearce <spearce@spearce.org>.</p> | |
</div> | |
<h2>Documentation</h2> | |
<div class="sectionbody"> | |
<p>Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.</p> | |
</div> | |
<h2>GIT</h2> | |
<div class="sectionbody"> | |
<p>Part of the <a href="git.html">git(1)</a> suite</p> | |
</div> | |
<div id="footer"> | |
<div id="footer-text"> | |
Last updated 08-Jun-2008 22:46:32 UTC | |
</div> | |
</div> | |
</body> | |
</html> |