From: Junio C Hamano <gitster@pobox.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 v2 2/2] Document the output format of ls-remote
Date: Wed, 22 Mar 2023 09:48:36 -0700 [thread overview]
Message-ID: <xmqqy1noenq3.fsf@gitster.g> (raw)
In-Reply-To: <44e79f0d69c86e3cf4363aaa10acda91bfa3e9ee.1679478573.git.gitgitgadget@gmail.com> (Sean Allred via GitGitGadget's message of "Wed, 22 Mar 2023 09:49:33 +0000")
"Sean Allred via GitGitGadget" <gitgitgadget@gmail.com> writes:
> +OUTPUT
> +------
> +
> +The output is in the format:
> +
> +------------
> +<OID> TAB <reference name> LF
> +------------
It seems that
$ git grep -i '<OID>' Documentation/
everybody spell the object identifer as "<oid>" in lowercase. TAB
and LF are better left uppercase.
$ git grep -i '<ref' Documentation/
says that we never say <reference name>. Almost everybody would say
<ref> here (and that curiously is what glossary-content.txt has---it
feels a bit funny to have "ref" not "reference" there, as the former
looks as if it were an informal abbreviation of the latter, but
'ref' seems to be the offical name of that thing).
The documentation for "show-branch" uses many <reference>s in the
description, which should be updated to match what its SYNOPSIS
section uses, which is <ref>.
> +For example,
> +
> +----
> +$ 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
> +----
Do we really need 9 lines of output to help readers understand the
output? I somehow feel that it would not add any clarity for the
readers to add more, when we already have 2 of the same kind in the
list, and it smells even more excessive to give more than 3 of the
same kind.
Oh, isn't it even worse? I see an EXAMPLE section that gives a
similar looking output. Do we need to add one more in a separate
section?
What is curious about your "example" is that usually the first entry
we see in the "ls-remote" output is for HEAD. Another curiousity
that is shared between yours and the existing examples is that
annotated tags should show their peeled representation, but the
examples are not showing (I suspect that existing ones were
documented way before we show peeled tags). For reference, the
output of running the command against my kernel.org repository
starts like so:
$ git ls-remote ko
27d43aaaf50ef0ae014b88bba294f93658016a2e HEAD
27d43aaaf50ef0ae014b88bba294f93658016a2e refs/heads/main
73876f4861cd3d187a4682290ab75c9dccadbc56 refs/heads/maint
27d43aaaf50ef0ae014b88bba294f93658016a2e refs/heads/master
c903bb7e22f8f86da64de537e5768ab0ca886f4b refs/heads/next
29b7b507b4e8ff04bf912512bb466ea39805b9e5 refs/heads/seen
860bc4360c4fcba0fe2df942984d87f8467af3df refs/heads/todo
d5aef6e4d58cfe1549adef5b436f3ace984e8c86 refs/tags/gitgui-0.10.0
3d654be48f65545c4d3e35f5d3bbed5489820930 refs/tags/gitgui-0.10.0^{}
33682a5e98adfd8ba4ce0e21363c443bd273eb77 refs/tags/gitgui-0.10.1
729ffa50f75a025935623bfc58d0932c65f7de2f refs/tags/gitgui-0.10.1^{}
...
So,
* correct <OID> and <reference name> in the format description.
* describe that <ref> in the output may be followed by ^{} to
show peeled representation of the preceding tag.
* update existing examples to show peeled tags.
are what I found missing in this patch.
Thanks for working on improving this documentation page.
next prev parent reply other threads:[~2023-03-22 16:48 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
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 [this message]
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=xmqqy1noenq3.fsf@gitster.g \
--to=gitster@pobox.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).