aboutsummaryrefslogtreecommitdiff
path: root/Documentation/git-describe.txt
diff options
context:
space:
mode:
authorJunio C Hamano <junkio@cox.net>2007-01-26 23:24:07 -0800
committerJunio C Hamano <junkio@cox.net>2007-01-28 02:08:51 -0800
commit1891261ed3ed52022ae5322b4db338f9d5112909 (patch)
tree5151efabbea135d4f270173239412467a2138194 /Documentation/git-describe.txt
parent237fb6ca7cbe45f88523ad367d0d703a039dff2d (diff)
downloadgit-1891261ed3ed52022ae5322b4db338f9d5112909.tar.gz
git-1891261ed3ed52022ae5322b4db338f9d5112909.tar.xz
Update describe documentation.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Diffstat (limited to 'Documentation/git-describe.txt')
-rw-r--r--Documentation/git-describe.txt31
1 files changed, 22 insertions, 9 deletions
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index b87783cf0..47a583d3a 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.
OPTIONS
@@ -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
SEARCH STRATEGY
---------------
@@ -97,7 +109,8 @@ 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
--------------