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

From: Junio C Hamano <[email-masked]>
Date: Tue, 21 Jan 2025 12:51:55 -0800

"D. Ben Knoble" <[email-masked]> writes:

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

$ git grep -e '^[`]*--\[no-\]' -e '^[`]*--no-' Documentation/

tells us that we also can write the above more like so:

	--progress::
	--no-progress::
		Progress status is reported ...

which may make it more palatable?  I didn't count and sift the hits
into two bin to see which style is more prevalent, but it may not be
a bad idea to consider unifying into one style.

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

Ones that are not marked with OPT_NONEG all take --no- variant, and
while going through the list of options we may realize some of them
should *not* take negated forms.  They all commonly share that
"giving --no-opt countermands an earlier --opt or the corresponding
configuration variable setting", and any "--opt" that has its own
corresponding configuration variable should already have the variable
documented in the paragraph, the body text may not have to be updated
at all in the best case (in other words, the only change required may
be to add lines of "--no-foo::" form next to existing "--foo::".

Thanks.