Document the output format of ls-remote
PATCH 1/1 Document the output format of ls-remote
From: Sean Allred <[email protected]>
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).
---
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(+)
Documentation/git-ls-remote.txt +18 -0
@@ -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
Signature · 1 line
gitgitgadget
Documentation/git-ls-remote.txt OPTIONS · line 99
Quoted 12 lines · Sean Allred via GitGitGadget
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 <[email protected]>---
Documentation/git-ls-remote.txt +4
-0@@ -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>'.
Documentation/git-ls-remote.txt OPTIONS · line 115
Quoted 12 lines
Documentation/git-ls-remote.txt +12
-0+---- +$ 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.
Quoted 11 lines · Eric Sunshine
Quoted 11 lines
+----
+$ git ls-remote
+950264636c68591989456e3ba0a5442f93152c1a refs/heads/main
+73876f4861cd3d187a4682290ab75c9dccadbc56 refs/heads/maintDocumentation/git-ls-remote.txt +7
-0+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
Quoted 8 lines
Quoted 1 line
+----
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.
Signature · 1 line
Felipe Contreras
Quoted 11 lines · Eric Sunshine
Quoted 1 line
+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.)
Quoted 4 lines
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
v2 cover Document the output format of ls-remote
In reply to Sean Allred via GitGitGadgetcc: Eric Sunshine [email protected] cc: Felipe Contreras [email protected] cc: Sean Allred [email protected]
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-remoteSignature · 1 line
gitgitgadget
PATCH v2 1/2 Update show-ref documentation for internal consistency
From: Sean Allred <[email protected]>
- 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.
--- Documentation/git-show-ref.txt | 40 ++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 14 deletions(-)
Documentation/git-show-ref.txt +26 -14
@@ -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 -----------------------------------------------------------------------------
Signature · 1 line
gitgitgadget
Re: [PATCH v2 1/2] Update show-ref documentation for internal consistency
Documentation/git-show-ref.txt OPTIONS · line 103
Quoted 5 lines · Sean Allred via GitGitGadget
Documentation/git-show-ref.txt +5
-0+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.
PATCH v2 2/2 Document the output format of ls-remote
In reply to Sean Allred via GitGitGadgetFrom: Sean Allred <[email protected]>
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).
--- Documentation/git-ls-remote.txt | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+)
Documentation/git-ls-remote.txt +24 -0
@@ -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 --------
Signature · 1 line
gitgitgadget
Documentation/git-ls-remote.txt OPTIONS · line 106
Quoted 8 lines · Sean Allred via GitGitGadget
Documentation/git-ls-remote.txt +8
-0+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>.
Quoted 4 lines
Documentation/git-ls-remote.txt +4
-0+For example, + +---- +$ git ls-remote
Documentation/git-ls-remote.txt OPTIONS · line 121
Quoted 10 lines
Documentation/git-ls-remote.txt +10
-0+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 2/2] Document the output format of ls-remote
Quoted 3 lines · Junio C Hamano
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.
--- Documentation/git-show-branch.txt | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-)
Documentation/git-show-branch.txt +4 -5
@@ -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.
v3 cover Document the output format of ls-remote
In reply to Sean Allred via GitGitGadgetThis iteration incorporates the feedback from v2 with additional patches to explain examples and remove redundant ones. These patches are of course explained in the commit messages, but they're in response to actual conversation [https://github.com/git/git/pull/1471#issuecomment-1547726140]
that I cannot seem to actually respond to for unknown technical reasons.
A bit off-topic: for the past few months, I have been having some serious trouble interacting with this list via the usual means
[https://github.com/git/git/pull/1471#issuecomment-1547726140] and would appreciate anyone may be able to diagnose the issue. I will be reaching out to the site/list owners as a first step (having exhausted my own investigation, of course). If you have any ideas, please feel free to email me directly / off-list or leave a comment on GitHub if you are so inclined -- I of course don't want this to become a support thread. I'd much rather keep conversation here to the topic of getting these patches merged :-)
Junio C Hamano (1):
show-branch doc: say <ref>, not <reference>
Sean Allred (5):
show-ref doc: update for internal consistency
ls-remote doc: remove redundant --tags example
ls-remote doc: show peeled tags in examples
ls-remote doc: explain what each example does
ls-remote doc: document the output format
Documentation/git-ls-remote.txt | 46 +++++++++++++++++++++++-------- Documentation/git-show-branch.txt | 16 +++++------ Documentation/git-show-ref.txt | 40 +++++++++++++++++---------- 3 files changed, 68 insertions(+), 34 deletions(-)
base-commit: 950264636c68591989456e3ba0a5442f93152c1a
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1471%2Fvermiculus%2Fsa%2Fdoc-ls-remote-output-format-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1471/vermiculus/sa/doc-ls-remote-output-format-v3
Pull-Request: https://github.com/git/git/pull/1471
Range-diff vs v2:
1: 4408b518810 ! 1: fe442c2041b Update show-ref documentation for internal consistency
@@ Metadata
Author: Sean Allred <[email protected]>
## Commit message ##
- Update show-ref documentation for internal consistency
+ show-ref doc: update for internal consistency
- 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.
+ This patch also swaps out 'SHA-1' language for the implementation-
+ agnostic 'OID' term where appropriate in preparation for supporting
+ different hashing algorithms.
@@ Documentation/git-show-ref.txt: OPTIONS
+The output is in the format:
+
+------------
-+<OID> SP <reference name> LF
++<oid> SP <ref> LF
+------------
+
+For example,
-: ----------- > 2: cd51a70f3ff show-branch doc: say <ref>, not <reference>
-: ----------- > 3: 8b644fb1203 ls-remote doc: remove redundant --tags example
-: ----------- > 4: dc0c5ba1751 ls-remote doc: show peeled tags in examples
-: ----------- > 5: 94380984533 ls-remote doc: explain what each example does
2: 44e79f0d69c ! 6: de57b8aa563 Document the output format of ls-remote
@@ Metadata
Author: Sean Allred <[email protected]>
## Commit message ##
- Document the output format of ls-remote
+ ls-remote doc: document the output format
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 <[email protected]>
## Documentation/git-ls-remote.txt ##
@@ Documentation/git-ls-remote.txt: OPTIONS
+The output is in the format:
+
+------------
-+<OID> TAB <reference name> LF
++<oid> TAB <ref> LF
+------------
+
-+For example,
++When `<ref>` is a tag, it may be followed by `^{}` to show its peeled
++representation.
+
+ EXAMPLES
+ --------
+
++* List all references (including symbolics and pseudorefs), peeling
++ tags:
+++
+----
+$ git ls-remote
++27d43aaaf50ef0ae014b88bba294f93658016a2e HEAD
+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
++73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{}
+----
+
- EXAMPLES
- --------
-
+ * List all references matching given patterns:
+ +
+ ----Signature · 1 line
gitgitgadget
PATCH v3 1/6 show-ref doc: update for internal consistency
From: Sean Allred <[email protected]>
- 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.
--- Documentation/git-show-ref.txt | 40 ++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 14 deletions(-)
Documentation/git-show-ref.txt +26 -14
@@ -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 <ref> 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 -----------------------------------------------------------------------------
Signature · 1 line
gitgitgadget
Re: [PATCH v3 1/6] show-ref doc: update for internal consistency
Quoted 19 lines · Sean Allred via GitGitGadget
- 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 <[email protected]>---
Documentation/git-show-ref.txt +5
-1@@ -96,7 +96,13 @@ OPTIONS -The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'. +The output is in the format: + +------------ +<oid> SP <ref> LF +------------ $ git show-ref --head --dereference
Documentation/git-show-ref.txt $ git show-ref --head --dereference · line 121
Quoted 7 lines
Documentation/git-show-ref.txt +5
-1@@ -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 +------------ $ git show-ref --heads --hash
Is the difference in case ("<oid>" vs. "<OID>") intentional between these two examples?
Re: [PATCH v3 1/6] show-ref doc: update for internal consistency
Quoted 23 lines · Eric Sunshine
Quoted 21 lines · Sean Allred via GitGitGadget
- 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 <[email protected]>---
Documentation/git-show-ref.txt +6
-2@@ -96,7 +96,13 @@ OPTIONS -The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'. +The output is in the format: + +------------ +<oid> SP <ref> LF +------------ $ 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:
Quoted 8 lines
Documentation/git-show-ref.txt $ git show-ref --head --dereference · line 128
Quoted 5 lines
Documentation/git-show-ref.txt +4
-0+ +------------ +<OID> LF +------------ $ git show-ref --heads --hashIs the difference in case ("<oid>" vs. "<OID>") intentional between these two examples?
I think it is an incomplete fix based on the suggestion I made for the previous round,
Re: [PATCH v3 1/6] show-ref doc: update for internal consistency
Quoted 34 lines · Junio C Hamano
Quoted 23 lines · Eric Sunshine
Quoted 21 lines · Sean Allred via GitGitGadget
- 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 <[email protected]>---
Documentation/git-show-ref.txt +6
-2@@ -96,7 +96,13 @@ OPTIONS -The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'. +The output is in the format: + +------------ +<oid> SP <ref> LF +------------ $ 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:Quoted 8 lines
Documentation/git-show-ref.txt $ git show-ref --head --dereference · line 128
Quoted 5 lines
Documentation/git-show-ref.txt +4
-0+ +------------ +<OID> LF +------------ $ git show-ref --heads --hashIs the difference in case ("<oid>" vs. "<OID>") intentional between these two examples?
Quoted 4 lines
I think it is an incomplete fix based on the suggestion I made for the previous round,
Nice catch; this has been fixed for the next iteration.
--
Sean Allred
Re: [PATCH v3 1/6] show-ref doc: update for internal consistency
In reply to Sean Allred via GitGitGadgetQuoted 8 lines · Sean Allred via GitGitGadget
From: Sean Allred <[email protected]>
- 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.
Making the last one into the third bullet item, e.g.
- Use OID instead of SHA-1, as we support different hashing algorithems these days.
would have been even easier to follow, but I'll let it pass.
In prose, "object name" would flow better than OID (the original would say not just "SHA-1" but use "SHA-1 hash" or somesuch in such a context), I would think. When used as a placeholder, OID would be perfectly fine (<oid>, where we used to write <hash> or <sha-1> or <SHA-1>).
Documentation/git-show-ref.txt OPTIONS · line 57
Quoted 7 lines
-s::
--hash[=<n>]::Documentation/git-show-ref.txt +2
-2- 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.
Not a problem you created, but I noticed we do not explain what "=<n>" up there does.
Documentation/git-show-ref.txt OPTIONS · line 105
Quoted 12 lines
Documentation/git-show-ref.txt +7
-1@@ -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 <ref> LF +------------ + +For example,
OK.
Documentation/git-show-ref.txt $ git show-ref --head --dereference · line 125
Quoted 12 lines
Documentation/git-show-ref.txt +7
-1@@ -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,
Let's consistently use <oid> in lowercase as the previous hunk.
Everything else looked great in this step. Thanks for working on this.
Re: [PATCH v3 1/6] show-ref doc: update for internal consistency
Quoted 6 lines · Junio C Hamano
Making the last one into the third bullet item, e.g.
- Use OID instead of SHA-1, as we support different hashing algorithems these days.
would have been even easier to follow, but I'll let it pass.
Easy enough to change for me; this will be addressed in the next iteration.
Quoted 5 lines
In prose, "object name" would flow better than OID (the original would say not just "SHA-1" but use "SHA-1 hash" or somesuch in such a context), I would think. When used as a placeholder, OID would be perfectly fine (<oid>, where we used to write <hash> or <sha-1> or <SHA-1>).
I've used 'apostrophes' to set off these terms (found as literals in the documentation that's changed) and explained/expanded 'OID' in the commit message.
Quoted 10 lines
Documentation/git-show-ref.txt OPTIONS · line 57
Quoted 7 lines
-s::
--hash[=<n>]::Documentation/git-show-ref.txt +2
-2- 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.Not a problem you created, but I noticed we do not explain what "=<n>" up there does.
Given I also don't know what it means, I'll let you spin this off into a separate bug report however you see fit :-) Just based on the diff context available above, it's odd to me also that -s apparently does not take an <n> -- whatever that may be.
Quoted 1 line
Everything else looked great in this step. Thanks for working on this.
Always a pleasure :-) Thanks for the review.
--
Sean Allred
PATCH v3 2/6 show-branch doc: say <ref>, not <reference>
In reply to Sean Allred via GitGitGadgetFrom: Junio C Hamano <[email protected]>
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.
--- Documentation/git-show-branch.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-)
Documentation/git-show-branch.txt +8 -8
@@ -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,10 +131,11 @@ are mutually exclusive. OUTPUT ------ -Given N <references>, 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. + +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. Following these N lines, one-line log for each commit is displayed, indented N places. If a commit is on the I-th
Signature · 1 line
gitgitgadget
PATCH v3 3/6 ls-remote doc: remove redundant --tags example
In reply to Sean Allred via GitGitGadgetFrom: Sean Allred <[email protected]>
The --tags option is already demonstrated in the later example that lists version-patterned tags. As it doesn't appear to add anything to the documentation, it ought to be removed to keep the documentation easier to read.
--- Documentation/git-ls-remote.txt | 7 ------- 1 file changed, 7 deletions(-)
Documentation/git-ls-remote.txt +0 -7
@@ -100,13 +100,6 @@ EXAMPLES -------- ---- -$ git ls-remote --tags . -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 -0918385dbd9656cab0d1d81ba7453d49bbc16250 refs/tags/junio-gpg-pub - $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen
Signature · 1 line
gitgitgadget
Re: [PATCH v3 3/6] ls-remote doc: remove redundant --tags example
Quoted 11 lines · Sean Allred via GitGitGadget
From: Sean Allred <[email protected]>
The --tags option is already demonstrated in the later example that lists version-patterned tags. As it doesn't appear to add anything to the documentation, it ought to be removed to keep the documentation easier to read.
Signed-off-by Sean Allred <[email protected]>--- Documentation/git-ls-remote.txt | 7 ------- 1 file changed, 7 deletions(-)
I like deletions ;-) Thanks.
PATCH v3 4/6 ls-remote doc: show peeled tags in examples
In reply to Sean Allred via GitGitGadgetFrom: Sean Allred <[email protected]>
Without --refs, this command will show peeled tags. Make this clearer in the examples to further mitigate the possibility of surprises in consuming scripts.
--- Documentation/git-ls-remote.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/git-ls-remote.txt +4 -4
@@ -106,10 +106,10 @@ c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen $ git remote add korg http://www.kernel.org/pub/scm/git/git.git $ git ls-remote --tags korg v\* -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 +485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2 +cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{} +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} ---- SEE ALSO
Signature · 1 line
gitgitgadget
Re: [PATCH v3 4/6] ls-remote doc: show peeled tags in examples
Quoted 10 lines · Sean Allred via GitGitGadget
From: Sean Allred <[email protected]>
Without
--refs, this command will show peeled tags. Make this clearer in the examples to further mitigate the possibility of surprises in consuming scripts.Signed-off-by Sean Allred <[email protected]>--- Documentation/git-ls-remote.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Nice attention to the detail. Thanks.
Quoted 19 lines
Documentation/git-ls-remote.txt +4
-4@@ -106,10 +106,10 @@ c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen $ git remote add korg http://www.kernel.org/pub/scm/git/git.git $ git ls-remote --tags korg v\* -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 +485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2 +cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{} +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} ---- SEE ALSO
PATCH v3 5/6 ls-remote doc: explain what each example does
In reply to Sean Allred via GitGitGadgetFrom: Sean Allred <[email protected]>
While it's good to have several examples to solidify the output pattern and generally demonstrate how to use the command, most other EXAMPLES sections (e.g., git-show-branch.txt, git-remote.txt) additionally describe the problem/situation to which the example is applicable.
Follow this example in the ls-remote documentation.
--- Documentation/git-ls-remote.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-)
Documentation/git-ls-remote.txt +7 -2
@@ -99,13 +99,18 @@ OPTIONS EXAMPLES -------- +* List all references matching given patterns: ++ ---- $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen +---- -$ git remote add korg http://www.kernel.org/pub/scm/git/git.git -$ git ls-remote --tags korg v\* +* List only tags matching a given wildcard pattern: ++ +---- +$ git ls-remote --tags http://www.kernel.org/pub/scm/git/git.git v\* 485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2 cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{} d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0
Signature · 1 line
gitgitgadget
PATCH v3 6/6 ls-remote doc: document the output format
In reply to Sean Allred via GitGitGadgetFrom: Sean Allred <[email protected]>
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.
--- Documentation/git-ls-remote.txt | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+)
Documentation/git-ls-remote.txt +24 -0
@@ -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. + EXAMPLES -------- +* List all references (including symbolics and pseudorefs), peeling + tags: ++ +---- +$ git ls-remote +27d43aaaf50ef0ae014b88bba294f93658016a2e HEAD +950264636c68591989456e3ba0a5442f93152c1a refs/heads/main +d9ab777d41f92a8c1684c91cfb02053d7dd1046b refs/heads/next +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} +---- + * List all references matching given patterns: + ----
Signature · 1 line
gitgitgadget
Re: [PATCH v3 6/6] ls-remote doc: document the output format
Quoted 23 lines · Sean Allred via GitGitGadget
From: Sean Allred <[email protected]>
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 <[email protected]>--- Documentation/git-ls-remote.txt | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+)Documentation/git-ls-remote.txt +1
-0@@ -96,9 +96,33 @@ OPTIONS separator (so `bar` matches `refs/heads/bar` but not `refs/heads/foobar`). +OUTPUT
Documentation/git-ls-remote.txt OPTIONS · line 109
Quoted 10 lines
Documentation/git-ls-remote.txt +10
-0+------ + +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.
Re: [PATCH v3 6/6] ls-remote doc: document the output format
Quoted 15 lines · Junio C Hamano
Documentation/git-ls-remote.txt OPTIONS · line 109
Quoted 11 lines
Documentation/git-ls-remote.txt +11
-0+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.
Quoted 4 lines
When showing an annotated tag, unless
--refsis 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.
This is clear to me, too (even reading it late at night -- kudos), so I've adopted your suggestion verbatim with a few minor formatting nits. Thanks!
Quoted 5 lines
The verb
peelis used in the explanation for the--refsoption, 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.
I'll add a tracking task for myself to potentially address this in the coming week or two, but I'll be happily surprised if someone else beats me to it :-) I agree it's out of scope for this series.
--
Sean Allred
v4 cover Document the output format of ls-remote
In reply to Sean Allred via GitGitGadgetThis iteration incorporates the feedback from v3. A capitalization inconsistency was fixed and the 'peeled tag' / ^{} discussion in git-ls-remote.txt was clarified.
Junio C Hamano (1):
show-branch doc: say <ref>, not <reference>
Sean Allred (5):
show-ref doc: update for internal consistency
ls-remote doc: remove redundant --tags example
ls-remote doc: show peeled tags in examples
ls-remote doc: explain what each example does
ls-remote doc: document the output format
Documentation/git-ls-remote.txt | 48 +++++++++++++++++++++++-------- Documentation/git-show-branch.txt | 16 +++++------ Documentation/git-show-ref.txt | 40 +++++++++++++++++--------- 3 files changed, 70 insertions(+), 34 deletions(-)
base-commit: 950264636c68591989456e3ba0a5442f93152c1a
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1471%2Fvermiculus%2Fsa%2Fdoc-ls-remote-output-format-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1471/vermiculus/sa/doc-ls-remote-output-format-v4
Pull-Request: https://github.com/git/git/pull/1471
Range-diff vs v3:
1: fe442c2041b ! 1: 49382e81e02 show-ref doc: update for internal consistency
@@ Commit message
- 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.
+ - Use 'OID' (for 'object ID') instead of 'SHA-1' as we support
+ different hashing algorithms these days.
@@ Documentation/git-show-ref.txt: $ git show-ref --head --dereference
+When using --hash (and not --dereference), the output is in the format:
+
+------------
-+<OID> LF
++<oid> LF
+------------
+
+For example,
2: cd51a70f3ff = 2: ea10e7964a9 show-branch doc: say <ref>, not <reference> 3: 8b644fb1203 = 3: cdd933e6fc3 ls-remote doc: remove redundant --tags example 4: dc0c5ba1751 = 4: 68c35f605ae ls-remote doc: show peeled tags in examples 5: 94380984533 = 5: cfb5dd0e87e ls-remote doc: explain what each example does 6: de57b8aa563 ! 6: 115dba15ce0 ls-remote doc: document the output format
@@ Documentation/git-ls-remote.txt: OPTIONS
+<oid> TAB <ref> LF
+------------
+
-+When <ref> is a tag, it may be followed by ^{} to show its peeled -+representation.
++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.
+
EXAMPLES
--------
Signature · 1 line
gitgitgadget
PATCH v4 1/6 show-ref doc: update for internal consistency
From: Sean Allred <[email protected]>
- Use inline-code syntax for options where appropriate.
- Use code blocks to clarify output format.
- Use 'OID' (for 'object ID') instead of 'SHA-1' as we support different hashing algorithms these days.
--- Documentation/git-show-ref.txt | 40 ++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 14 deletions(-)
Documentation/git-show-ref.txt +26 -14
@@ -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 <ref> 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 -----------------------------------------------------------------------------
Signature · 1 line
gitgitgadget
PATCH v4 2/6 show-branch doc: say <ref>, not <reference>
In reply to Sean Allred via GitGitGadgetFrom: Junio C Hamano <[email protected]>
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.
--- Documentation/git-show-branch.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-)
Documentation/git-show-branch.txt +8 -8
@@ -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,10 +131,11 @@ are mutually exclusive. OUTPUT ------ -Given N <references>, 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. + +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. Following these N lines, one-line log for each commit is displayed, indented N places. If a commit is on the I-th
Signature · 1 line
gitgitgadget
PATCH v4 3/6 ls-remote doc: remove redundant --tags example
In reply to Sean Allred via GitGitGadgetFrom: Sean Allred <[email protected]>
The --tags option is already demonstrated in the later example that lists version-patterned tags. As it doesn't appear to add anything to the documentation, it ought to be removed to keep the documentation easier to read.
--- Documentation/git-ls-remote.txt | 7 ------- 1 file changed, 7 deletions(-)
Documentation/git-ls-remote.txt +0 -7
@@ -100,13 +100,6 @@ EXAMPLES -------- ---- -$ git ls-remote --tags . -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 -0918385dbd9656cab0d1d81ba7453d49bbc16250 refs/tags/junio-gpg-pub - $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen
Signature · 1 line
gitgitgadget
PATCH v4 4/6 ls-remote doc: show peeled tags in examples
In reply to Sean Allred via GitGitGadgetFrom: Sean Allred <[email protected]>
Without --refs, this command will show peeled tags. Make this clearer in the examples to further mitigate the possibility of surprises in consuming scripts.
--- Documentation/git-ls-remote.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/git-ls-remote.txt +4 -4
@@ -106,10 +106,10 @@ c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen $ git remote add korg http://www.kernel.org/pub/scm/git/git.git $ git ls-remote --tags korg v\* -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 +485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2 +cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{} +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} ---- SEE ALSO
Signature · 1 line
gitgitgadget
PATCH v4 5/6 ls-remote doc: explain what each example does
In reply to Sean Allred via GitGitGadgetFrom: Sean Allred <[email protected]>
While it's good to have several examples to solidify the output pattern and generally demonstrate how to use the command, most other EXAMPLES sections (e.g., git-show-branch.txt, git-remote.txt) additionally describe the problem/situation to which the example is applicable.
Follow this example in the ls-remote documentation.
--- Documentation/git-ls-remote.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-)
Documentation/git-ls-remote.txt +7 -2
@@ -99,13 +99,18 @@ OPTIONS EXAMPLES -------- +* List all references matching given patterns: ++ ---- $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen +---- -$ git remote add korg http://www.kernel.org/pub/scm/git/git.git -$ git ls-remote --tags korg v\* +* List only tags matching a given wildcard pattern: ++ +---- +$ git ls-remote --tags http://www.kernel.org/pub/scm/git/git.git v\* 485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2 cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{} d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0
Signature · 1 line
gitgitgadget
PATCH v4 6/6 ls-remote doc: document the output format
In reply to Sean Allred via GitGitGadgetFrom: Sean Allred <[email protected]>
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.
--- Documentation/git-ls-remote.txt | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+)
Documentation/git-ls-remote.txt +26 -0
@@ -96,9 +96,35 @@ 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 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. + EXAMPLES -------- +* List all references (including symbolics and pseudorefs), peeling + tags: ++ +---- +$ git ls-remote +27d43aaaf50ef0ae014b88bba294f93658016a2e HEAD +950264636c68591989456e3ba0a5442f93152c1a refs/heads/main +d9ab777d41f92a8c1684c91cfb02053d7dd1046b refs/heads/next +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} +---- + * List all references matching given patterns: + ----
Signature · 1 line
gitgitgadget