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

[Patrick Steinhardt <ps@pks.im>]

[-- Attachment #1: Type: text/plain, Size: 1823 bytes --]

On Thu, Jul 25, 2024 at 08:03:06AM -0700, Junio C Hamano wrote:
> 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.

> 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]