| Message ID | pull.1471.git.git.1679153586903.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Document the output format of ls-remote | expand |
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.
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.
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
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 --------