Re: [PATCH] Document the output format of ls-remote

From: Sean Allred <allred.sean@gmail.com>
Date: Mar 19, 2023, 21:36 UTC
Message-ID: <m0ttyg8lqw.fsf@epic96565.epic.com>
In-Reply-To: <CAPig+cQ+__c0CVspBgVxcGrzj8AnJJKKaQr-ofT4oLS-C-bQtw@mail.gmail.com>

Eric Sunshine <sunshine@sunshineco.com> writes:

Show 11 quoted lines

>> +The output is in the format: '<SHA-1 ID>' '<tab>' '<reference>'.
>
> The angle brackets in the '<foo>' notation indicate a placeholder,
> however, in the output, TAB is literal, it is never replaced with
> something else. So, to be more accurate and less confusing, we should
> instead say:
>
>     The output is in the format: '<SHA-1 ID>' 'TAB' '<reference>'.
>
> I understand that you copied '<tab>' from git-show-ref.txt, but we
> don't need to replicate that mistake.

I too found that odd. I took inspiration from git-rev-parse.txt for the next iteration. I've pushed that to my branch (which you can fetch if interested), but I'll wait another day or two for more review before resubmitting. (I took the liberty of fixing git-show-ref.txt as well.)

> Moreover, these days, we support hash algorithms beyond merely SHA-1,
> so the first placeholder should probably talk about object-ID instead:
>
>     The output is in the format: '<OID>' 'TAB' '<reference>'.

Good call; I've made this update and it will be included in the next iteration.

-- Sean Allred