Re: [PATCH] grep: document negated line-number, column long options

>
> "D. Ben Knoble via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: "D. Ben Knoble" <ben.knoble+github@gmail.com>
> >
> > 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."

>
> >  --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.

>
>  - 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`.

>
> 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.