Re: [PATCH v3 6/6] ls-remote doc: document the output format

From: Junio C Hamano <gitster@pobox.com>
Date: May 15, 2023, 20:01 UTC
Message-ID: <xmqqfs7x8iu4.fsf@gitster.g>
In-Reply-To: <de57b8aa563f20b45e18dbe45abaa14a2971da13.1684152793.git.gitgitgadget@gmail.com>

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

Show 33 quoted lines

> From: Sean Allred <allred.sean@gmail.com>
>
> While well-established, the output format of ls-remote was not actually
> documented. This patch adds an OUTPUT section to the documentation
> following the format of git-show-ref.txt (which has similar semantics).
>
> Add a basic example immediately after this to solidify the 'normal'
> output format.
>
> Signed-off-by: Sean Allred <allred.sean@gmail.com>
> ---
>  Documentation/git-ls-remote.txt | 24 ++++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
>
> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
> index c0b2facef48..15313f2b10d 100644
> --- a/Documentation/git-ls-remote.txt
> +++ b/Documentation/git-ls-remote.txt
> @@ -96,9 +96,33 @@ OPTIONS
>  	separator (so `bar` matches `refs/heads/bar` but not
>  	`refs/heads/foobar`).
>  
> +OUTPUT
> +------
> +
> +The output is in the format:
> +
> +------------
> +<oid> TAB <ref> LF
> +------------
> +
> +When `<ref>` is a tag, it may be followed by `^{}` to show its peeled
> +representation.

While I can guess what the above wants to say, the above does not quite "click" for me for some reason. Here is my attempt.

    When showing an annotated tag, unless `--refs` is given, two
    such lines are shown, one with the refname for the tag itself as
    <ref>, and another with <ref> followed by `^{}`.  The `<oid>` on
    the latter line shows the name of the object the tag points at.

The verb `peel` is used in the explanation for the `--refs` option, but there is no formal definition of what it means in the glossary.

We may want to do something about it, but we probably would want to leave it outside the scope of this series.

Other than that, looking great.

Thanks.