More precise description of 'git describe --abbrev'

Also adds a note about why the output in the examples might give
different output today.

Signed-off-by: Gisle Aas <gisle@aas.no>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index b231dbb947791bb4fc5cde552e8c736b3558ca0a..e9dbca7d87bade4126cd45477b69478894518168 100644 (file)
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -44,7 +44,9 @@ OPTIONS
 
 --abbrev=<n>::
        Instead of using the default 7 hexadecimal digits as the
 
 --abbrev=<n>::
        Instead of using the default 7 hexadecimal digits as the

-       abbreviated object name, use <n> digits.
+       abbreviated object name, use <n> digits, or as many digits
+       as needed to form a unique object name.  An <n> of 0
+       will suppress long format, only showing the closest tag.

 
 --candidates=<n>::
        Instead of considering only the 10 most recent tags as
 
 --candidates=<n>::
        Instead of considering only the 10 most recent tags as


@@ -68,8 +70,8 @@ OPTIONS
        This is useful when you want to see parts of the commit object name
        in "describe" output, even when the commit in question happens to be
        a tagged version.  Instead of just emitting the tag name, it will
        This is useful when you want to see parts of the commit object name
        in "describe" output, even when the commit in question happens to be
        a tagged version.  Instead of just emitting the tag name, it will

-       describe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2
-       that points at object deadbeef....).
+       describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2
+       that points at object deadbee....).

 
 --match <pattern>::
        Only consider tags matching the given pattern (can be used to avoid
 
 --match <pattern>::
        Only consider tags matching the given pattern (can be used to avoid


@@ -108,7 +110,7 @@ the output shows the reference path as well:
        [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
        tags/v1.0.0-21-g975b
 
        [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
        tags/v1.0.0-21-g975b
 

-       [torvalds@g5 git]$ git describe --all HEAD^
+       [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^

        heads/lt/describe-7-g975b
 
 With --abbrev set to 0, the command can be used to find the
        heads/lt/describe-7-g975b
 
 With --abbrev set to 0, the command can be used to find the


@@ -117,6 +119,13 @@ closest tagname without any suffix:
        [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
        tags/v1.0.0
 
        [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
        tags/v1.0.0
 

+Note that the suffix you get if you type these commands today may be
+longer than what Linus saw above when he ran this command, as your
+git repository may have new commits whose object names begin with
+975b that did not exist back then, and "-g975b" suffix alone may not
+be sufficient to disambiguate these commits.
+
+

 SEARCH STRATEGY
 ---------------
 
 SEARCH STRATEGY
 ---------------