On Tue, Oct 24, 2023 at 9:11 AM Patrick Steinhardt <ps@xxxxxx> wrote: > The synopsis treats the `--verify` and the implicit mode the same. They > are slightly different though: > > - They accept different sets of flags. > > - The implicit mode accepts patterns while the `--verify` mode > accepts references. > > Split up the synopsis for these two modes such that we can disambiguate > those differences. Good. When reading [2/12], my immediate thought was that such a documentation change was needed. > Signed-off-by: Patrick Steinhardt <ps@xxxxxx> > --- > diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt > @@ -8,9 +8,12 @@ git-show-ref - List references in a local repository > SYNOPSIS > -'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference] > +'git show-ref' [-q | --quiet] [--head] [-d | --dereference] > [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] > [--heads] [--] [<pattern>...] > +'git show-ref' --verify [-q | --quiet] [-d | --dereference] > + [-s | --hash[=<n>]] [--abbrev[=<n>]] > + [--] [<ref>...] > 'git show-ref' --exclude-existing[=<pattern>] What does it mean to request "quiet" for the plain `git show-ref` mode? That seems pointless and counterintuitive. Even though this mode may accept --quiet as a quirk of implementation, we probably shouldn't be promoting its use in the documentation. Moreover, the blurb for --quiet later in the document: Do not print any results to stdout. When combined with --verify, this can be used to silently check if a reference exists. should probably be rephrased since it currently implies that it may be used with modes other than --verify, but that's not really the case (implementation quirks aside). This also raises the question as to whether an interlock should be added to disallow --quiet with plain `git show-ref`, much like the interlock preventing --exclude-existing and --verify from being used together. Ideally, such an interlock ought to be added, but I wouldn't be surprised to learn that doing so would break someone's existing tooling which insensibly uses --quiet with plain `git show-ref`.
