Re: [PATCH] doc: Improve description for rev-parse --short

From: Junio C Hamano <gitster@pobox.com>
Date: May 30, 2017, 04:10 UTC
Message-ID: <xmqq1sr7dly4.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20170528143322.8580-1-asheiduk@gmail.com>

Andreas Heiduk <asheiduk@gmail.com> writes:

> First: `git rev-parse --short` without a number does use a fixed default but
> `core.abbrev` which in turn uses `find_unique_abbrev` internally.

... hence the value gives mere minumum. I like your updated text that clarifies this point.

> Second: `--short` implies `--verify` since the beginning (d50125085a), so
> it cannot be used for bulk-shortening ids unfortunately.

The fact you have to say "Nth:" hints that this is better done as two patch series. Then you can avoid saying a vague "Improve" on the subject, that leaves the "git shortlog" readers wondering what exactly you improved.

Show 30 quoted lines

> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> ---
>  Documentation/config.txt        | 1 +
>  Documentation/git-rev-parse.txt | 4 +++-
>  2 files changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index e0b9fd0bc..158cb588b 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -862,6 +862,7 @@ core.abbrev::
>  	computed based on the approximate number of packed objects
>  	in your repository, which hopefully is enough for
>  	abbreviated object names to stay unique for some time.
> +	The minimum length is 4.
>  
>  add.ignoreErrors::
>  add.ignore-errors (deprecated)::
> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
> index c40c47044..7a7421c8e 100644
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -140,7 +140,9 @@ can be used.
>  --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.
> +	the effective value of the configuration variable `core.abbrev` (see
> +	linkgit:git-config[1]) is used.  The minimum length is 4.  The length
> +	may be exceeded to ensure unique object names.	Implies `--verify`.

"Implies --verify" is less important than the fact that multiple object names cannot be given from the end-users' (and readers') point of view, no? The sentence in the pre-context still hints (incorrectly) that we might take multiple names---that would want to be corrected, no?

Let me try.

    --short[=length]::
	Take a single object name, and output a prefix of the object
	name whose length is at least the specified length and
	sufficient to ensure uniqueness of the name.  The minimum
	length is 4.  When no length is given, the effective value
	of the `core.abbrev` configuration variable is used.

Thanks.

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