On Wed, Apr 30, 2025 at 3:19 PM Junio C Hamano [off-list ref] wrote:

"Kristoffer Haugsbakk" [off-list ref] writes:

quoted

Many options are documented as `--[no-]`.

    git grep --fixed-string -- '--[no-]' Documentation/ ':(exclude)Documentation/RelNotes/'

This is explained in gitcli(7), “Enhanced Option Parser” (for some
commands), “Negating options”:

       Options with long option names can be negated by prefixing
       --no-. For example, git branch has the option --track which is on
       by default. You can use --no-track to override that
       behaviour. The same goes for --color and --no-color.

A concern might be that changing `--single-branch` in this way would be
inconsistent with the overall style.

A pair of quick counts:

    $ git grep -E -e '^`?--no-' Documentation/ | wc -l
    189
    $ git grep -E -e '^`?--\[no-\]' Documentation/ | wc -l
    80

I think we should try to unify to the following style:

    `--frotz=<string>`::
    `--no-frotz`::
        When `--frotz` is given, the command does THIS using the
        given argument <string> IN THIS WAY.  The default is not to
        to THIS, unless SUCH AND SUCH CONDITION, in which case THAT
        is used implicitly as <string>.  To disable THIS even when
        SUCH AND SUCH CONDITION is met, use `--no-frotz`.

That is:

 * Both positive and negative form are given separately as a
   headline item, so that "grep" would work well;

 * The description should be unified, so that it is clear to readers
   what happens when the positive form is given, when the negative
   form is given, and when neither is given.

 * Mark-up the text that the users MUST input literally inside a
   pair of backquotes.

Which means that existing "--[no-]opt::" heading should become two
lines, "`--opt`::" and "`--no-opt`::".

Thanks.

See also https://lore.kernel.org/git/xmqqjzanzy8k.fsf@gitster.g/ (local),
where I had some similar questions (and got similar answers). We also
merged 4ad47d2de3 (gitcli: document that command line trumps config
and env, 2025-01-16) as a result.

If I'm reading right, this suggestion differs from the previous
conversation that it's worth splitting --[no-]opt into --opt/--no-opt,
which might be valuable for searches of the kind Lino described.

I did eventually push beeabf89 (vim: try harder to find long options,
2025-01-19) [1] to my Dotfiles to work around the current
documentation patterns. I press either `-x` or `_XXX` when searching
for an option (short x, long XXX) in a manual page with those Vim
keybindings, but hopefully the patterns are useful to other people.
For long options, that's

/^\C\v\s*(-[^,]*,\s*)?--(\[no-\])?

[1]: https://github.com/benknoble/Dotfiles/commit/beeabf89

-- 
D. Ben Knoble