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

[Junio C Hamano <gitster@pobox.com>]

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