Re: [PATCH 10/12] builtin/show-ref: explicitly spell out different modes in synopsis
From: Eric Sunshine <hidden>
Date: 2023-10-24 19:39:42
On Tue, Oct 24, 2023 at 9:11 AM Patrick Steinhardt [off-list ref] 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.
quoted hunk ↗ jump to hunk
Signed-off-by: Patrick Steinhardt <redacted> ---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`.