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

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

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

Show 19 quoted lines

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

This is clear to me, too (even reading it late at night -- kudos), so I've adopted your suggestion verbatim with a few minor formatting nits. Thanks!

Show 5 quoted lines

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

I'll add a tracking task for myself to potentially address this in the coming week or two, but I'll be happily surprised if someone else beats me to it :-) I agree it's out of scope for this series.

-- Sean Allred