[PATCH] Document the output format of ls-remote

[PATCH] Document the output format of ls-remote

[Sean Allred via GitGitGadget]

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

Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
    Document the output format of ls-remote

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1471%2Fvermiculus%2Fsa%2Fdoc-ls-remote-output-format-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1471/vermiculus/sa/doc-ls-remote-output-format-v1
Pull-Request: https://github.com/git/git/pull/1471

 Documentation/git-ls-remote.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index ff3da547ddb..04cdd933b0a 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -96,6 +96,24 @@ OPTIONS
 	separator (so `bar` matches `refs/heads/bar` but not
 	`refs/heads/foobar`).
 
+OUTPUT
+------
+
+The output is in the format: '<SHA-1 ID>' '<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
+----
+
 EXAMPLES
 --------
 

base-commit: 950264636c68591989456e3ba0a5442f93152c1a
-- 
gitgitgadget

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

[Eric Sunshine]

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.

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

[Felipe Contreras]

On Sun, Mar 19, 2023 at 11:52 AM Eric Sunshine <sunshine@sunshineco.com> wrote:

> > +----
> > +$ 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.

AsciiDoc implementations follow the AsciiDoc specification, and
everything between ---- is considered a source code block, so tabs
should be interpreted as such.

-- 
Felipe Contreras

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

[Sean Allred]

Eric Sunshine <sunshine@sunshineco.com> writes:
>> +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.

I too found that odd. I took inspiration from git-rev-parse.txt for the
next iteration. I've pushed that to my branch (which you can fetch if
interested), but I'll wait another day or two for more review before
resubmitting. (I took the liberty of fixing git-show-ref.txt as well.)

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

Good call; I've made this update and it will be included in the next
iteration.

--
Sean Allred

[PATCH v2 0/2] Document the output format of ls-remote

[Sean Allred via GitGitGadget]

cc: Eric Sunshine sunshine@sunshineco.com cc: Felipe Contreras
felipe.contreras@gmail.com cc: Sean Allred allred.sean@gmail.com

Sean Allred (2):
  Update show-ref documentation for internal consistency
  Document the output format of ls-remote

 Documentation/git-ls-remote.txt | 24 ++++++++++++++++++++
 Documentation/git-show-ref.txt  | 40 +++++++++++++++++++++------------
 2 files changed, 50 insertions(+), 14 deletions(-)


base-commit: 950264636c68591989456e3ba0a5442f93152c1a
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1471%2Fvermiculus%2Fsa%2Fdoc-ls-remote-output-format-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1471/vermiculus/sa/doc-ls-remote-output-format-v2
Pull-Request: https://github.com/git/git/pull/1471

Range-diff vs v1:

 -:  ----------- > 1:  4408b518810 Update show-ref documentation for internal consistency
 1:  a80059d90da ! 2:  44e79f0d69c Document the output format of ls-remote
     @@ Documentation/git-ls-remote.txt: OPTIONS
      +OUTPUT
      +------
      +
     -+The output is in the format: '<SHA-1 ID>' '<tab>' '<reference>'.
     ++The output is in the format:
     ++
     ++------------
     ++<OID> TAB <reference name> LF
     ++------------
     ++
     ++For example,
      +
      +----
      +$ git ls-remote

-- 
gitgitgadget

[PATCH v2 1/2] Update show-ref documentation for internal consistency

[Sean Allred via GitGitGadget]

From: Sean Allred <allred.sean@gmail.com>

- Use inline-code syntax for options where appropriate.
- Use code blocks to clarify output format.

This patch also swaps out 'SHA-1' language for the
implementation-agnostic 'OID' term where appropriate in preparation for
supporting different hashing algorithms.

Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
 Documentation/git-show-ref.txt | 40 ++++++++++++++++++++++------------
 1 file changed, 26 insertions(+), 14 deletions(-)

diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index d1d56f68b43..cb876a342a3 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -23,7 +23,7 @@ particular ref exists.
 
 By default, shows the tags, heads, and remote refs.
 
-The --exclude-existing form is a filter that does the inverse. It reads
+The `--exclude-existing` form is a filter that does the inverse. It reads
 refs from stdin, one ref per line, and shows those that don't exist in
 the local repository.
 
@@ -47,14 +47,14 @@ OPTIONS
 -d::
 --dereference::
 
-	Dereference tags into object IDs as well. They will be shown with "{caret}{}"
+	Dereference tags into object IDs as well. They will be shown with `{caret}{}`
 	appended.
 
 -s::
 --hash[=<n>]::
 
-	Only show the SHA-1 hash, not the reference name. When combined with
-	--dereference the dereferenced tag will still be shown after the SHA-1.
+	Only show the OID, not the reference name. When combined with
+	`--dereference`, the dereferenced tag will still be shown after the OID.
 
 --verify::
 
@@ -70,15 +70,15 @@ OPTIONS
 -q::
 --quiet::
 
-	Do not print any results to stdout. When combined with `--verify` this
+	Do not print any results to stdout. When combined with `--verify`, this
 	can be used to silently check if a reference exists.
 
 --exclude-existing[=<pattern>]::
 
-	Make 'git show-ref' act as a filter that reads refs from stdin of the
-	form "`^(?:<anything>\s)?<refname>(?:\^{})?$`"
+	Make `git show-ref` act as a filter that reads refs from stdin of the
+	form `^(?:<anything>\s)?<refname>(?:\^{})?$`
 	and performs the following actions on each:
-	(1) strip "{caret}{}" at the end of line if any;
+	(1) strip `{caret}{}` at the end of line if any;
 	(2) ignore if pattern is provided and does not head-match refname;
 	(3) warn if refname is not a well-formed refname and skip;
 	(4) ignore if refname is a ref that exists in the local repository;
@@ -96,7 +96,13 @@ OPTIONS
 OUTPUT
 ------
 
-The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'.
+The output is in the format:
+
+------------
+<OID> SP <reference name> LF
+------------
+
+For example,
 
 -----------------------------------------------------------------------------
 $ git show-ref --head --dereference
@@ -110,7 +116,13 @@ $ git show-ref --head --dereference
 ...
 -----------------------------------------------------------------------------
 
-When using --hash (and not --dereference) the output format is: '<SHA-1 ID>'
+When using `--hash` (and not `--dereference`), the output is in the format:
+
+------------
+<OID> LF
+------------
+
+For example,
 
 -----------------------------------------------------------------------------
 $ git show-ref --heads --hash
@@ -142,10 +154,10 @@ When using the `--verify` flag, the command requires an exact path:
 
 will only match the exact branch called "master".
 
-If nothing matches, 'git show-ref' will return an error code of 1,
+If nothing matches, `git show-ref` will return an error code of 1,
 and in the case of verification, it will show an error message.
 
-For scripting, you can ask it to be quiet with the "--quiet" flag, which
+For scripting, you can ask it to be quiet with the `--quiet` flag, which
 allows you to do things like
 
 -----------------------------------------------------------------------------
@@ -157,11 +169,11 @@ to check whether a particular branch exists or not (notice how we don't
 actually want to show any results, and we want to use the full refname for it
 in order to not trigger the problem with ambiguous partial matches).
 
-To show only tags, or only proper branch heads, use "--tags" and/or "--heads"
+To show only tags, or only proper branch heads, use `--tags` and/or `--heads`
 respectively (using both means that it shows tags and heads, but not other
 random references under the refs/ subdirectory).
 
-To do automatic tag object dereferencing, use the "-d" or "--dereference"
+To do automatic tag object dereferencing, use the `-d` or `--dereference`
 flag, so you can do
 
 -----------------------------------------------------------------------------
-- 
gitgitgadget

[PATCH v2 2/2] Document the output format of ls-remote

[Sean Allred via GitGitGadget]

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

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 ff3da547ddb..9913ab3f83d 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -96,6 +96,30 @@ OPTIONS
 	separator (so `bar` matches `refs/heads/bar` but not
 	`refs/heads/foobar`).
 
+OUTPUT
+------
+
+The output is in the format:
+
+------------
+<OID> TAB <reference name> LF
+------------
+
+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
+----
+
 EXAMPLES
 --------
 
-- 
gitgitgadget

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

[Junio C Hamano]

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

Re: [PATCH v2 1/2] Update show-ref documentation for internal consistency

[Junio C Hamano]

"Sean Allred via GitGitGadget" <gitgitgadget@gmail.com> writes:

> +The output is in the format:
> +
> +------------
> +<OID> SP <reference name> LF
> +------------

The same comment for <OID> and <reference name> from my review for
[2/2] applies here.

Other than that, looking good.

Thanks.

Re* [PATCH v2 2/2] Document the output format of ls-remote

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

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

I forgot to list this in the list of actionable items at the end of
my review message I am responding to, so here is a patch to help us
not forget about it ;-).

----- >8 -----
Subject: show-branch doc: say <ref>, not <reference>

The glossary defines 'ref' as the official name of the thing,
and the output from "git grep -e '<ref' Documentation/" shows
that most everybody uses <ref>, not <reference>.  In addition,
the page already says <ref> in its SYNOPSIS section for the
command when it is used in the mode to follow the reflogs.

Strictly speaking, many references of these should be updated to
<commit> after adding an explanation on how these <commit>s are
discovered (i.e. we take <rev>, <glob>, or <ref> and starting from
these commits, follow their ancestry or reflog entries to list
commits), but that would be a lot bigger change I would rather not
to do in this patch, whose primary purpose is to make the existing
documentation more consistent.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-show-branch.txt | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git c/Documentation/git-show-branch.txt w/Documentation/git-show-branch.txt
index 71f608b1ff..0874c01e37 100644
--- c/Documentation/git-show-branch.txt
+++ w/Documentation/git-show-branch.txt
@@ -74,8 +74,7 @@ OPTIONS
 	that is the common ancestor of all the branches.  This
 	flag tells the command to go <n> more common commits
 	beyond that.  When <n> is negative, display only the
-	<reference>s given, without showing the commit ancestry
-	tree.
+	<ref>s given, without showing the commit ancestry tree.
 
 --list::
 	Synonym to `--more=-1`
@@ -88,8 +87,8 @@ OPTIONS
 	the case of three or more commits.
 
 --independent::
-	Among the <reference>s given, display only the ones that
-	cannot be reached from any other <reference>.
+	Among the <ref>s given, display only the ones that
+	cannot be reached from any other <ref>.
 
 --no-name::
 	Do not show naming strings for each commit.
@@ -132,7 +131,7 @@ are mutually exclusive.
 
 OUTPUT
 ------
-Given N <references>, the first N lines are the one-line
+Given N <ref>s, the first N lines are the one-line
 description from their commit message.  The branch head that is
 pointed at by $GIT_DIR/HEAD is prefixed with an asterisk `*`
 character while other heads are prefixed with a `!` character.