Re: [PATCH] More precise description of 'git describe --abbrev'

[Junio C Hamano <gitster@pobox.com>]

Gisle Aas <gisle@aas.no> writes:

> Also make the examples show what 'git describe' actually outputs
> currently.  I guess the default --abbrev value has been changed from 4
> to 7 at some point.

Some are good changes, but I do not think the example with --abbrev=4 is.

$ git describe 975bf9cf5ad5d440f98f464ae8124609a4835ce1
v1.3.2-216-g975bf9c
$ git describe 975b31dc6e12fba8f7b067ddbe32230995e05400
v1.0.0-21-g975b31d

Next time somebody adds a new object whose name happens to begin with
975b3 you would need to update the example output.

> Signed-off-by: Gisle Aas <gisle@aas.no>
> ---
>  Documentation/git-describe.txt |   12 +++++++-----
>  1 files changed, 7 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
> index b231dbb..743eb95 100644
> --- 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
> -	abbreviated object name, use <n> digits.
> +	abbreviated object name, use <n> digits or as many digits
> +	are 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
> @@ -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
> -	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
> @@ -106,10 +108,10 @@ 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-21-g975b
> +	tags/v1.0.0-21-g975b3
>
>  	[torvalds@g5 git]$ git describe --all HEAD^
> -	heads/lt/describe-7-g975b
> +	heads/lt/describe-7-g975b31d
>
>  With --abbrev set to 0, the command can be used to find the
>  closest tagname without any suffix:
> -- 
> 1.6.2.95.g934f7