Re: [PATCH 10/12] builtin/show-ref: explicitly spell out different modes in synopsis
- From
Eric Sunshine <sunshine@sunshineco.com>
- Date
- Oct 24, 2023, 19:39 UTC
- Message-ID
- <CAPig+cQ=VhRm40oW=TQYzy2NXKNJm4QVQhtw3FAKsFRn12qYLA@mail.gmail.com>
- In-Reply-To
- <adcfa7a6a9d8fb6f915faf77df52362544cd590e.1698152926.git.ps@pks.im>
On Tue, Oct 24, 2023 at 9:11 AM Patrick Steinhardt <ps@pks.im> wrote:
Show 10 quoted lines
> 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.
Show 13 quoted lines
> Signed-off-by: Patrick Steinhardt <ps@pks.im> > --- > 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`.