| Message ID | de57b8aa563f20b45e18dbe45abaa14a2971da13.1684152793.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Document the output format of ls-remote | expand |
"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.
Junio C Hamano <gitster@pobox.com> writes: >> +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. 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! > 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. 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
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. + 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: + ----