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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 16, 2025, 22:54 UTC
Message-ID: <xmqqy0zanzdw.fsf@gitster.g>
In-Reply-To: <pull.1878.git.git.1737066042014.gitgitgadget@gmail.com>

"D. Ben Knoble via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 8 quoted lines

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

Show 6 quoted lines

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