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

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Mar 19, 2023, 17:30 UTC
Message-ID: <CAPig+cQ+__c0CVspBgVxcGrzj8AnJJKKaQr-ofT4oLS-C-bQtw@mail.gmail.com>
In-Reply-To: <pull.1471.git.git.1679153586903.gitgitgadget@gmail.com>

On Sat, Mar 18, 2023 at 11:51 AM Sean Allred via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 12 quoted lines

> 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).
>
> Signed-off-by: Sean Allred <allred.sean@gmail.com>
> ---
> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
> @@ -96,6 +96,24 @@ OPTIONS
> +OUTPUT
> +------
> +
> +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.

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

Show 12 quoted lines

> +----
> +$ git ls-remote
> +950264636c68591989456e3ba0a5442f93152c1a       refs/heads/main
> +73876f4861cd3d187a4682290ab75c9dccadbc56       refs/heads/maint
> +d9ab777d41f92a8c1684c91cfb02053d7dd1046b       refs/heads/next
> +74a0ffe000da036ce4ca843d991a7c6b8c246a08       refs/heads/seen
> +860bc4360c4fcba0fe2df942984d87f8467af3df       refs/heads/todo
> +d4ca2e3147b409459955613c152220f4db848ee1       refs/tags/v2.40.0
> +8810a79228a149a9773bf9c75f381fca27a6a80e       refs/tags/v2.40.0-rc0
> +f899c182d0bffb6e915da7c8db9be202b144c098       refs/tags/v2.40.0-rc1
> +6bed3304b2b2f1cf440ca3050b57a7cf3a3fe687       refs/tags/v2.40.0-rc2
> +----

I'm not an Asciidoc expert, but despite the fact that the real git-ls-remote output emits TABs, I'm not sure we really want TABs in the documentation since various Asciidoc implementations may render it differently. Also, we don't seem to have any embedded TABs like this in other documentation. It probably would be better to use spaces in the documentation.

Those nits aside, the patch makes sense and is well-explained.