path: root/Documentation/git-describe.txt
diff options
authorJunio C Hamano <>2007-01-27 07:24:07 (GMT)
committerJunio C Hamano <>2007-01-28 10:08:51 (GMT)
commit1891261ed3ed52022ae5322b4db338f9d5112909 (patch)
tree5151efabbea135d4f270173239412467a2138194 /Documentation/git-describe.txt
parent237fb6ca7cbe45f88523ad367d0d703a039dff2d (diff)
Update describe documentation.
Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/git-describe.txt')
1 files changed, 22 insertions, 9 deletions
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 @@ DESCRIPTION
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.
@@ -52,12 +52,18 @@ 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:
@@ -68,10 +74,16 @@ With --all, the command can use branch heads as references, so
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
@@ -97,7 +109,8 @@ will be the smallest number of commits possible.
Written by Linus Torvalds <>, but somewhat
-butchered by Junio C Hamano <>
+butchered by Junio C Hamano <>. Later significantly
+updated by Shawn Pearce <>.