Merge branch 'maint'

[git.git] / Documentation / git-describe.txt

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index b87783cf0956bba11ef0101a9ac80fe1f91e3f80..ac23e28f2759222bb67fcf2445c229e918d96211 100644 (file)
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -8,14 +8,14 @@ git-describe - Show the most recent tag that is reachable from a commit
 
 SYNOPSIS
 --------
-'git-describe' [--all] [--tags] [--abbrev=<n>] <committish>...
+'git-describe' [--all] [--tags] [--contains] [--abbrev=<n>] <committish>...
 
 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
@@ -31,6 +31,11 @@ OPTIONS
        Instead of using only the annotated tags, use any tag
        found in `.git/refs/tags`.
 
+--contains::
+       Instead of finding the tag that predates the commit, find
+       the tag that comes after the commit, and thus contains it.
+       Automatically implies --tags.
+
 --abbrev=<n>::
        Instead of using the default 8 hexadecimal digits as the
        abbreviated object name, use <n> digits.
@@ -52,12 +57,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 +79,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 +114,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
 --------------
@@ -106,4 +124,3 @@ Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel
 GIT
 ---
 Part of the gitlink:git[7] suite
-