Re: [PATCH 1/1] show-ref: improve short help messages of options

From: Patrick Steinhardt <ps@pks.im>
Date: Jul 26, 2024, 12:28 UTC
Message-ID: <ZqOWUrynjUN2A5TM@tanuki>
In-Reply-To: <xmqqr0bhldjp.fsf@gitster.g>

On Thu, Jul 25, 2024 at 08:03:06AM -0700, Junio C Hamano wrote:

Show 12 quoted lines

> Patrick Steinhardt <ps@pks.im> writes:
> 
> > Agreed, I think that this is a sensible change. In practice, this
> > feature can also be combined with `--head`, so in that spirit we might
> > even change it to:
> >
> >     "only show tags (can be combined with --branches and --head)"
> >
> > Not sure though whether this is getting too noisy?
> 
> It is somewhat an oxymoron that "*only* show X" can be combined with
> "*only* show Y" in the first place.

Yeah, this is the root of the problem why those braces are required in the first place. But that being said, the option is somewhat funny because it indeed limits what we show to only show tags. The fact that it can be combined with other options to expand on what it shows doesn't change that, so I think "only" is okay-ish even though it certainly is not perfect.

Show 11 quoted lines

> For a reader to accept it without finding it awkward, the reader
> must understand that
> 
>  (1) the command shows by default everything, but
> 
>  (2) if any of these "only show" options are given, the command
>      stops showing everything and the user can pick which subset of
>      "only show" options to give, which work additively.
> 
> But if the reader knows that much already, it is redundant to say
> "can be combined with", isn't it?

Hum. I personally find the way that this is worded intuitive and think that I would find it helpful when reading it as a less-knowledgeable user. But naturally, I'm quite biased and may be too unimaginative to come up with a better wording.

Meanwhile, I think that the proposed change strictly improves this message and thus don't see a reason not to take it. Unless we see somebody come up with a less-awkward solution, that is.

Patrick