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

[Gisle Aas <gisle@aas.no>]

On Thu, Oct 29, 2009 at 23:47, Junio C Hamano <gitster@pobox.com> wrote:
> 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.

Yeah, I know, but I don't think that's a big deal.  So do you want an
updated patch for that?  We could either simply remove this example or
make it use --abbrev=10 or something like that.

--Gisle


>
>> 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
>