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

From: Junio C Hamano <gitster@pobox.com>
Date: May 15, 2023, 19:48 UTC
Message-ID: <xmqqttwd8jg5.fsf@gitster.g>
In-Reply-To: <fe442c2041b01985a4ecb0f2e9651231af2a439b.1684152793.git.gitgitgadget@gmail.com>

"Sean Allred via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 8 quoted lines

> From: Sean Allred <allred.sean@gmail.com>
>
> - Use inline-code syntax for options where appropriate.
> - Use code blocks to clarify output format.
>
> This patch also swaps out 'SHA-1' language for the implementation-
> agnostic 'OID' term where appropriate in preparation for supporting
> different hashing algorithms.

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.

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

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

Show 12 quoted lines

> @@ -96,7 +96,13 @@ OPTIONS
>  OUTPUT
>  ------
>  
> -The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'.
> +The output is in the format:
> +
> +------------
> +<oid> SP <ref> LF
> +------------
> +
> +For example,

OK.

Show 12 quoted lines

> @@ -110,7 +116,13 @@ $ git show-ref --head --dereference
>  ...
>  -----------------------------------------------------------------------------
>  
> -When using --hash (and not --dereference) the output format is: '<SHA-1 ID>'
> +When using `--hash` (and not `--dereference`), the output is in the format:
> +
> +------------
> +<OID> LF
> +------------
> +
> +For example,

Let's consistently use <oid> in lowercase as the previous hunk.

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