From: Eric Sunshine <sunshine@sunshineco.com>
To: Sean Allred via GitGitGadget <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, Sean Allred <code@seanallred.com>,
Sean Allred <allred.sean@gmail.com>
Subject: Re: [PATCH] Document the output format of ls-remote
Date: Sun, 19 Mar 2023 13:30:08 -0400 [thread overview]
Message-ID: <CAPig+cQ+__c0CVspBgVxcGrzj8AnJJKKaQr-ofT4oLS-C-bQtw@mail.gmail.com> (raw)
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:
> 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>'.
> +----
> +$ 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.
next prev parent reply other threads:[~2023-03-19 17:30 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-03-18 15:33 [PATCH] Document the output format of ls-remote Sean Allred via GitGitGadget
2023-03-19 17:30 ` Eric Sunshine [this message]
2023-03-19 19:25 ` Felipe Contreras
2023-03-19 21:36 ` Sean Allred
2023-03-22 9:49 ` [PATCH v2 0/2] " Sean Allred via GitGitGadget
2023-03-22 9:49 ` [PATCH v2 1/2] Update show-ref documentation for internal consistency Sean Allred via GitGitGadget
2023-03-22 16:50 ` Junio C Hamano
2023-03-22 9:49 ` [PATCH v2 2/2] Document the output format of ls-remote Sean Allred via GitGitGadget
2023-03-22 16:48 ` Junio C Hamano
2023-03-22 17:13 ` Re* " Junio C Hamano
2023-05-15 12:13 ` [PATCH v3 0/6] " Sean Allred via GitGitGadget
2023-05-15 12:13 ` [PATCH v3 1/6] show-ref doc: update for internal consistency Sean Allred via GitGitGadget
2023-05-15 16:58 ` Eric Sunshine
2023-05-15 17:27 ` Junio C Hamano
2023-05-19 3:51 ` Sean Allred
2023-05-15 19:48 ` Junio C Hamano
2023-05-19 3:55 ` Sean Allred
2023-05-15 12:13 ` [PATCH v3 2/6] show-branch doc: say <ref>, not <reference> Junio C Hamano via GitGitGadget
2023-05-15 12:13 ` [PATCH v3 3/6] ls-remote doc: remove redundant --tags example Sean Allred via GitGitGadget
2023-05-15 19:52 ` Junio C Hamano
2023-05-15 12:13 ` [PATCH v3 4/6] ls-remote doc: show peeled tags in examples Sean Allred via GitGitGadget
2023-05-15 19:53 ` Junio C Hamano
2023-05-15 12:13 ` [PATCH v3 5/6] ls-remote doc: explain what each example does Sean Allred via GitGitGadget
2023-05-15 12:13 ` [PATCH v3 6/6] ls-remote doc: document the output format Sean Allred via GitGitGadget
2023-05-15 20:01 ` Junio C Hamano
2023-05-19 4:04 ` Sean Allred
2023-05-19 4:17 ` [PATCH v4 0/6] Document the output format of ls-remote Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 1/6] show-ref doc: update for internal consistency Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 2/6] show-branch doc: say <ref>, not <reference> Junio C Hamano via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 3/6] ls-remote doc: remove redundant --tags example Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 4/6] ls-remote doc: show peeled tags in examples Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 5/6] ls-remote doc: explain what each example does Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 6/6] ls-remote doc: document the output format Sean Allred via GitGitGadget
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAPig+cQ+__c0CVspBgVxcGrzj8AnJJKKaQr-ofT4oLS-C-bQtw@mail.gmail.com \
--to=sunshine@sunshineco.com \
--cc=allred.sean@gmail.com \
--cc=code@seanallred.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).