On Thu, Jan 16, 2025 at 5:54 PM Junio C Hamano <gitster@xxxxxxxxx> wrote:
>
> "D. Ben Knoble via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes:
>
> > From: "D. Ben Knoble" <ben.knoble+github@xxxxxxxxx>
> >
> > I set grep.lineNumber and grep.column on in my user .gitconfig;
> > sometimes, when I script over the results from `git grep`, I want no
> > prefixes, only a filename prefix, or only the matched text. I usually
> > comment out the relevant config sections or use `git -c` to tweak them for
> > a single run---why? Because `git help grep` doesn't mention they can be
> > disabled any other way!
>
> While I am somewhat sympathetic, I'd prefer to see it done in a more
> centralized way, so that people understand that *any* Boolean option
> and associated configuratrion can be negated by prefixing "--no-" to
> the base option, instead of having to learn "Ah, today I learned
> that --line-number can be negated with --no-line-number thanks to
> this patch."
This makes sense, though I want to also make it discoverable. Relying
on `git help cli` is not quite as discoverable as I would like, since
I wouldn't have thought to look there myself—further, it isn't always
clear _which_ options can be negated in the way `git help cli`
describes. [Returning to this midway through writing] Upon
experimentation it appears the answer is "all long options"—TIL!
I wonder if there is some way to point more folks to the conventions
of `git help cli`?
>
> > --line-number::
> > Prefix the line number to matching lines.
> >
> > +--no-line-number::
> > + Turn off line number prefixes, even when the configuration file or a
> > + previous option requests them.
>
> So, this is not quite welcome for two reasons.
>
> - We do not want to see us keep repeating "configuration file" for
> any negatable option, as it is common to all command line options
> and associated configuration knob that the command line option
> trumps the configuration.
Fair—as you noticed, this isn't really spelled out anywhere, but you
have patches to fix that below. Thanks!
>
> - We do not want to see us keep repeating the substantial part of
> the body of the base option by adding a separate entry for a
> corresponding variant with "--no-".
>
> Even though an approach to centrally teach people that they can
> negate a Boolean option "--opt" by saying "--no-opt", and thatn they
> can negate a configured setting with a command line option is
> desirable, for such an approach to work, the documentation must
> somehow signal which option is Boolean.
>
> The way we do so is by doing something like this.
>
> $ git grep -e '^--\[no-\]' Documentation/
>
> An example entry (this is from blame-options.txt) looks like this.
>
> --[no-]progress::
> Progress status is reported on the standard error stream
> by default when it is attached to a terminal. This flag
> enables progress reporting even if not attached to a
> terminal. Can't use `--progress` together with `--porcelain`
> or `--incremental`.
Fair enough; I dislike the `[no-]` formatting because it is harder to
build into a search pattern (I have Vim keybindings to search manuals
for long and short options that it breaks), but I will probably live
with it and adjust my search patterns rather than complain further.
>
> As nobody complains that "I cannot understand what --no-progress,
> which is described in the above, means", there must be a central
> place where we describe this convention ("git help cli" talks about
> negating options).
>
> So I suspect you'd only need to do something like this
>
> ---line-number::
> +--[no-]line-number::
> Prefix the line number ...
>
> in your patch, without doing anything else.
>
> Thanks.
Sounds like you would prefer a re-roll that does something similar for
`--[no-]line-number` and `--[no-]column`? I suppose I have to
wonder—for which Boolean options is it worth doing so?
