On Sat, Mar 18, 2023 at 11:51 AM Sean Allred via GitGitGadget
<gitgitgadget@xxxxxxxxx> wrote:
> 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@xxxxxxxxx>
> ---
> 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>'.
> +----
> +$ 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.
