-----------
The command finds the most recent tag that is reachable from a
commit, and if the commit itself is pointed at by the tag, shows
-the tag. Otherwise, it suffixes the tag name with abbreviated
-object name of the commit.
+the tag. Otherwise, it suffixes the tag name with the number of
+additional commits and the abbreviated object name of the commit.
OPTIONS
Instead of using the default 8 hexadecimal digits as the
abbreviated object name, use <n> digits.
+--candidates=<n>::
+ 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.
+
+--debug::
+ Verbosely display information about the searching strategy
+ being employed to standard error. The tag name will still
+ be printed to standard out.
EXAMPLES
--------
With something like git.git current tree, I get:
[torvalds@g5 git]$ git-describe parent
- v1.0.4-g2414721b
+ v1.0.4-14-g2414721
i.e. the current head of my "parent" branch is based on v1.0.4,
-but since it has a few commits on top of that, it has added the
-git hash of the thing to the end: "-g" + 8-char shorthand for
-the commit `2414721b194453f058079d897d13c4e377f92dc6`.
+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.
+
+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 `2414721b194453f058079d897d13c4e377f92dc6`).
Doing a "git-describe" on a tag-name will just show the tag name:
the output shows the reference path as well:
[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
- tags/v1.0.0-g975b
+ tags/v1.0.0-21-g975b
[torvalds@g5 git]$ git describe --all HEAD^
- heads/lt/describe-g975b
+ heads/lt/describe-7-g975b
+
+With --abbrev set to 0, the command can be used to find the
+closest tagname without any suffix:
+
+ [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
+ tags/v1.0.0
+
+SEARCH STRATEGY
+---------------
+
+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.
+
+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.
+
+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.
Author
------
Written by Linus Torvalds <torvalds@osdl.org>, but somewhat
-butchered by Junio C Hamano <junkio@cox.net>
+butchered by Junio C Hamano <junkio@cox.net>. Later significantly
+updated by Shawn Pearce <spearce@spearce.org>.
Documentation
--------------