| Message ID | fe442c2041b01985a4ecb0f2e9651231af2a439b.1684152793.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Document the output format of ls-remote | expand |
On Mon, May 15, 2023 at 8:13 AM Sean Allred via GitGitGadget <gitgitgadget@gmail.com> wrote: > - 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> > --- > diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt > @@ -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: > + > +------------ > +<OID> LF > +------------ > $ git show-ref --heads --hash Is the difference in case ("<oid>" vs. "<OID>") intentional between these two examples?
Eric Sunshine <sunshine@sunshineco.com> writes: > On Mon, May 15, 2023 at 8:13 AM Sean Allred via GitGitGadget > <gitgitgadget@gmail.com> wrote: >> - 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> >> --- >> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt >> @@ -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: >> + >> +------------ >> +<OID> LF >> +------------ >> $ git show-ref --heads --hash > > Is 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, cf. https://lore.kernel.org/git/xmqqsfdwenn3.fsf@gitster.g/
"Sean Allred via GitGitGadget" <gitgitgadget@gmail.com> writes: > 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. 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>). > -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. Not a problem you created, but I noticed we do not explain what "=<n>" up there does. > @@ -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. > @@ -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.
Junio C Hamano <gitster@pobox.com> writes: > Eric Sunshine <sunshine@sunshineco.com> writes: > >> On Mon, May 15, 2023 at 8:13 AM Sean Allred via GitGitGadget >> <gitgitgadget@gmail.com> wrote: >>> - 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> >>> --- >>> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt >>> @@ -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: >>> + >>> +------------ >>> +<OID> LF >>> +------------ >>> $ git show-ref --heads --hash >> >> Is 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, > > cf. https://lore.kernel.org/git/xmqqsfdwenn3.fsf@gitster.g/ Nice catch; this has been fixed for the next iteration. -- Sean Allred
Junio C Hamano <gitster@pobox.com> writes: > 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. > 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. >> -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. > > 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. > Everything else looked great in this step. Thanks for working on this. Always a pleasure :-) Thanks for the review. -- Sean Allred
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index d1d56f68b43..be048bf1816 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 <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 -----------------------------------------------------------------------------