Update describe documentation.
Signed-off-by: Junio C Hamano <junkio@cox.net>
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index b87783c..47a583d 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -14,8 +14,8 @@
-----------
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
@@ -52,12 +52,18 @@
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:
@@ -68,10 +74,16 @@
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
---------------
@@ -97,7 +109,8 @@
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
--------------
