From: Junio C Hamano <gitster@pobox.com>
To: "Sean Allred via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, Eric Sunshine <sunshine@sunshineco.com>,
Sean Allred <allred.sean@gmail.com>,
Sean Allred <code@seanallred.com>
Subject: Re: [PATCH v3 6/6] ls-remote doc: document the output format
Date: Mon, 15 May 2023 13:01:39 -0700 [thread overview]
Message-ID: <xmqqfs7x8iu4.fsf@gitster.g> (raw)
In-Reply-To: <de57b8aa563f20b45e18dbe45abaa14a2971da13.1684152793.git.gitgitgadget@gmail.com> (Sean Allred via GitGitGadget's message of "Mon, 15 May 2023 12:13:13 +0000")
"Sean Allred via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Sean Allred <allred.sean@gmail.com>
>
> 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).
>
> Add a basic example immediately after this to solidify the 'normal'
> output format.
>
> Signed-off-by: Sean Allred <allred.sean@gmail.com>
> ---
> Documentation/git-ls-remote.txt | 24 ++++++++++++++++++++++++
> 1 file changed, 24 insertions(+)
>
> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
> index c0b2facef48..15313f2b10d 100644
> --- a/Documentation/git-ls-remote.txt
> +++ b/Documentation/git-ls-remote.txt
> @@ -96,9 +96,33 @@ OPTIONS
> separator (so `bar` matches `refs/heads/bar` but not
> `refs/heads/foobar`).
>
> +OUTPUT
> +------
> +
> +The output is in the format:
> +
> +------------
> +<oid> TAB <ref> LF
> +------------
> +
> +When `<ref>` is a tag, it may be followed by `^{}` to show its peeled
> +representation.
While I can guess what the above wants to say, the above does not
quite "click" for me for some reason. Here is my attempt.
When showing an annotated tag, unless `--refs` is given, two
such lines are shown, one with the refname for the tag itself as
<ref>, and another with <ref> followed by `^{}`. The `<oid>` on
the latter line shows the name of the object the tag points at.
The verb `peel` is used in the explanation for the `--refs` option,
but there is no formal definition of what it means in the glossary.
We may want to do something about it, but we probably would want to
leave it outside the scope of this series.
Other than that, looking great.
Thanks.
next prev parent reply other threads:[~2023-05-15 20:06 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
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 [this message]
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=xmqqfs7x8iu4.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 \
--cc=sunshine@sunshineco.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).