Subject: Re: [PATCH v3 1/6] show-ref doc: update for internal consistency

From: Sean Allred <[email-masked]>
Date: Thu, 18 May 2023 22:55:39 -0500

Junio C Hamano <[email-masked]> writes:
> Making the last one into the third bullet item, e.g.
>
>     - Use OID instead of SHA-1, as we support different hashing
>       algorithems these days.
>
> would have been even easier to follow, but I'll let it pass.

Easy enough to change for me; this will be addressed in the next
iteration.

> In prose, "object name" would flow better than OID (the original
> would say not just "SHA-1" but use "SHA-1 hash" or somesuch in such
> a context), I would think.  When used as a placeholder, OID would be
> perfectly fine (<oid>, where we used to write <hash> or <sha-1> or
> <SHA-1>).

I've used 'apostrophes' to set off these terms (found as literals in the
documentation that's changed) and explained/expanded 'OID' in the commit
message.

>>  -s::
>>  --hash[=<n>]::
>>
>> -	Only show the SHA-1 hash, not the reference name. When combined with
>> -	--dereference the dereferenced tag will still be shown after the SHA-1.
>> +	Only show the OID, not the reference name. When combined with
>> +	`--dereference`, the dereferenced tag will still be shown after the OID.
>
> Not a problem you created, but I noticed we do not explain what
> "=<n>" up there does.

Given I also don't know what it means, I'll let you spin this off into a
separate bug report however you see fit :-) Just based on the diff
context available above, it's odd to me also that `-s` apparently does
not take an `<n>` -- whatever that may be.

> Everything else looked great in this step.  Thanks for working on this.

Always a pleasure :-) Thanks for the review.

--
Sean Allred