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

From: Sean Allred <allred.sean@gmail.com>
Date: May 19, 2023, 03:55 UTC
Message-ID: <m0353tug01.fsf@epic96565.epic.com>
In-Reply-To: <xmqqttwd8jg5.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

Show 6 quoted lines

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

Show 5 quoted lines

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

Show 10 quoted lines

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