On Wed, Apr 30, 2025 at 3:19 PM Junio C Hamano <gitster@xxxxxxxxx> wrote: > > "Kristoffer Haugsbakk" <kristofferhaugsbakk@xxxxxxxxxxxx> writes: > > > 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/, 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
