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

From: Andreas Heiduk <asheiduk@gmail.com>
Date: May 30, 2017, 20:40 UTC
Message-ID: <787ad1fe-9923-d47d-79b0-8b0aebd8eb9b@gmail.com>
In-Reply-To: <xmqq1sr7dly4.fsf@gitster.mtv.corp.google.com>

Am 30.05.2017 um 06:10 schrieb Junio C Hamano:

Show 24 quoted lines

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

Your are right about s/names/name/ in the pretext.

But I think that the link to the `--verify` option is still important. The text there talks about when something is output, exit codes and about `^{type}` peeling. Also `--quiet` is linked to `--verify` and hence relevant here.

So I'd like to patch your text to this:

  --short[=length]::
	Same as `--verify` but output only 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.

And I'd like to move the section up right to `--verify` and `--quiet`. The options in this section are not sorted alphabetically anyways and the relevant parts would be adjacent. Is that OK?

ALso: Did you remove the `linkgit` by intention or just by accident?