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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 21, 2025, 20:51 UTC
Message-ID: <xmqqjzanzy8k.fsf@gitster.g>
In-Reply-To: <CALnO6CBUbmZaL1NuG2RxrvuxbUexKdtKfgYi2jTDY3QEa9NQkA@mail.gmail.com>

"D. Ben Knoble" <ben.knoble+github@gmail.com> writes:

Show 15 quoted lines

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