[PATCH] doc: explain default option for rev-parse --short

[PATCH] doc: explain default option for rev-parse --short

[André Werlang]

From 2b1c229153a89c7608e64b87d2f933704c18b7ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Werlang?= <beppe85@gmail.com>
Date: Thu, 18 May 2017 10:50:11 -0300
Subject: [PATCH] doc: explain default option for rev-parse --short
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Git 2.11 introduced a computation to guess the default length
for commit short hashes. The documentation isn't updated.

Signed-off-by: André Werlang <beppe85@gmail.com>
---
 Documentation/git-rev-parse.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 7241e96..b49f053 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -139,8 +139,10 @@ can be used.
 --short::
 --short=number::
  Instead of outputting the full SHA-1 values of object names try to
- abbreviate them to a shorter unique name. When no length is specified
- 7 is used. The minimum length is 4.
+ abbreviate them to a shorter unique name. When no length is specified,
+ it is guessed from the number of objects in the repository. In any case,
+ the actual length will be enough to identify the object unambiguously
+ in the current state of the repository. The minimum length is 4.

 --symbolic::
  Usually the object names are output in SHA-1 form (with

Re: [PATCH] doc: explain default option for rev-parse --short

[Jeff King]

On Thu, May 18, 2017 at 11:03:00AM -0300, André Werlang wrote:

> Git 2.11 introduced a computation to guess the default length
> for commit short hashes. The documentation isn't updated.

Thanks for the patch. I think this is going in the right direction, but
I have a few minor comments.

> From 2b1c229153a89c7608e64b87d2f933704c18b7ae Mon Sep 17 00:00:00 2001
> From: =?UTF-8?q?Andr=C3=A9=20Werlang?= <beppe85@gmail.com>
> Date: Thu, 18 May 2017 10:50:11 -0300
> Subject: [PATCH] doc: explain default option for rev-parse --short
> MIME-Version: 1.0
> Content-Type: text/plain; charset=UTF-8
> Content-Transfer-Encoding: 8bit

These headers are redundant with what's in your email headers and can be
dropped.

> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
> index 7241e96..b49f053 100644
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -139,8 +139,10 @@ can be used.
>  --short::
>  --short=number::
>   Instead of outputting the full SHA-1 values of object names try to
> - abbreviate them to a shorter unique name. When no length is specified
> - 7 is used. The minimum length is 4.
> + abbreviate them to a shorter unique name. When no length is specified,
> + it is guessed from the number of objects in the repository. In any case,
> + the actual length will be enough to identify the object unambiguously
> + in the current state of the repository. The minimum length is 4.

This is definitely an improvement, though I wonder if we should mention
that we default to core.abbrev (which in turn defaults to the "auto"
behavior).

It looks like there are a few other mentions of "7" with respect to
"--abbrev": git-branch.txt, git-describe.txt, git-blame.txt. Those
should probably get the same treatment.

There are a few other "--abbrev" options (e.g., ls-files and ls-tree)
that don't mention "7". But while we're fixing the others, it may be
worth giving them all consistent text.

-Peff

Re: [PATCH] doc: explain default option for rev-parse --short

[André Werlang]

Hey Jeff, I'll take a look at improving the text and the other commands.

Thanks for the response. I'll get back to you soonish.

André

2017-05-18 12:59 GMT-03:00 Jeff King <peff@peff.net>:
> On Thu, May 18, 2017 at 11:03:00AM -0300, André Werlang wrote:
>
>> Git 2.11 introduced a computation to guess the default length
>> for commit short hashes. The documentation isn't updated.
>
> Thanks for the patch. I think this is going in the right direction, but
> I have a few minor comments.
>
>> From 2b1c229153a89c7608e64b87d2f933704c18b7ae Mon Sep 17 00:00:00 2001
>> From: =?UTF-8?q?Andr=C3=A9=20Werlang?= <beppe85@gmail.com>
>> Date: Thu, 18 May 2017 10:50:11 -0300
>> Subject: [PATCH] doc: explain default option for rev-parse --short
>> MIME-Version: 1.0
>> Content-Type: text/plain; charset=UTF-8
>> Content-Transfer-Encoding: 8bit
>
> These headers are redundant with what's in your email headers and can be
> dropped.
>
>> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
>> index 7241e96..b49f053 100644
>> --- a/Documentation/git-rev-parse.txt
>> +++ b/Documentation/git-rev-parse.txt
>> @@ -139,8 +139,10 @@ can be used.
>>  --short::
>>  --short=number::
>>   Instead of outputting the full SHA-1 values of object names try to
>> - abbreviate them to a shorter unique name. When no length is specified
>> - 7 is used. The minimum length is 4.
>> + abbreviate them to a shorter unique name. When no length is specified,
>> + it is guessed from the number of objects in the repository. In any case,
>> + the actual length will be enough to identify the object unambiguously
>> + in the current state of the repository. The minimum length is 4.
>
> This is definitely an improvement, though I wonder if we should mention
> that we default to core.abbrev (which in turn defaults to the "auto"
> behavior).
>
> It looks like there are a few other mentions of "7" with respect to
> "--abbrev": git-branch.txt, git-describe.txt, git-blame.txt. Those
> should probably get the same treatment.
>
> There are a few other "--abbrev" options (e.g., ls-files and ls-tree)
> that don't mention "7". But while we're fixing the others, it may be
> worth giving them all consistent text.
>
> -Peff



-- 
André Werlang