Setting Defaults for 3.0?

[epage]

Defaults are important

• A lot of people won't deviate from defaults, so by having good defaults we improve the overall ecosystem
• Clap's API surface area is large, making it unlikely for people to know a setting exists and to find its name.

A quick survey of what seem like well respected CLIs in Rust

• ripgrep
  • AppSettings::UnifiedHelpMessage
  • AppSettings::AllArgsOverrideSelf
• bat
  • ColoredHelp (manually turned off when colors are disabled, is this needed?)
  • DeriveDisplayOrder
  • UnifiedHelpMessage
  • HidePossibleValuesInHelp
  • ArgsNegateSubcommands
  • AllowExternalSubcommands
  • DisableHelpSubcommand
  • VersionlessSubcommands
• fd
  • ColoredHelp (manually turned off when colors are disabled, is this needed?)
  • DeriveDisplayOrder
• hyperfine
  • ColoredHelp (manually turned off when colors are disabled, is this needed?)
  • UnifiedHelpMessage
  • NextLineHelp
  • HidePossibleValuesInHelp
• tokei
  • ColoredHelp
• delta
  • ColorAlways
  • ColoredHelp
  • DeriveDisplayOrder
• skim
• starship
  • SubcommandRequiredElseHelp

Based on these trends, I propose clap3s defaults be:

• UnifiedHelpMessage
  • Personally, the distinction between flag and argument is arbitrary from the user perspective. imo any visual grouping should be user driven, like with Python's argparse
• DeriveDisplayOrder
  • Most users probably logically order their arguments. For very large argument lists, leaving it to be sorted might make sense since it can be hard to search. I've rarely seen that though.
• ColoredHelp
• AllArgsOverrideSelf
  • This seems like the most questionable. It helps a lot when automating CLIs though because you can work append-only

[epage]

@BurntSushi I'd be interested in your input on this:

• Have you seen any downsides to AllArgsOverrideSelf that might not make it a good default?
• Is there a reason you hadn't enabled DeriveDisplayOrder or ColoredHelp?

[BurntSushi]

• I don't believe I've seen any downsides to AllArgsOverrideSelf. If you want a stricter interface, I could see disabling it. But it feels like something I'd probably always want enabled to be honest.
• I don't enable DeriveDisplayOrder because I do actually want everything to be alphabetical. See group command line args into affected processing steps BurntSushi/ripgrep#1814 and organized flags in man page according to logical section? BurntSushi/ripgrep#1022 for more details.
• I don't enable ColoredHelp IIRC because it added a second library for terminal coloring to my dependency tree. I didn't see colored help as useful enough to justify the extra dependency.

[epage]

Just found out clap3 has grouping of arguments in help
BurntSushi/ripgrep#1814 (comment)

Makes me unsure whether to make UnifiedHelpMessage a default or not.

[pksunkara]

The rule with clap 3.0, is that if a setting is supposed to be turned on by default, then it should not be a setting in the first place. So, the answer to the question here is that none of these settings should be enabled by default.

[pksunkara]

Honestly, I don't think any of these 3 should be default turned on.

[BurntSushi]

@pksunkara ........ mind... elaborating?

[epage]

I agree, more context would be useful. As a heavy user of clap, I keep forgetting to fine tune these and am inconsistent across my programs on which I set, for no other reason than the friction involved. Having good defaults makes a big difference, both in terms of the quality of the library but also the quality of the ecosystem that uses the library.

[pksunkara]

• ColoredHelp should not be turned on by default because it depends on a feature (even if the feature is turned on by default)
• UnifiedHelpMessage has never been default since the beginning of clap project. And I think it's better if flags and args are grouped separately in the help message.
• DeriveDisplayOrder should not be default because the options/subcommands in help message should be in alphabetic order which is the pattern followed by most CLI tools.

[epage]

Going to break these out into distinct threads to make this easier to follow

[epage]

@pksunkara

ColoredHelp should not be turned on by default because it depends on a feature (even if the feature is turned on by default)

[0x5c]

I recently started using clap, and it took a bit to comprehend help messages were not coloured despite the color feature being the default. Lots of head scratching followed by "really?".

I understand the potential argument against having any colourisation by default (ie not a default feature), but regardless of the feature being default or not, colourisation should be the default when the feature is enabled.

[epage]

To be clear, color is used in other places, like error messages. This flag is is specifically for --help. I wish knew the rationale for why this needed its own flag compared to the rest since it isn't obvious why the distinction is made.

[0x5c]

Oh yeah, the coloured error messages were a big part of the confusion

As for the rationale, maybe the colouring wasn't added everywhere at the same time?

[epage]

@pksunkara any update?

[epage]

I split this out into #2806

[epage]

@pksunkara

UnifiedHelpMessage has never been default since the beginning of clap project. And I think it's better if flags and args are grouped separately in the help message.

[BurntSushi]

Yes, I disabled this immediately, because the default organization made zero sense to me. Without looking it up, I have no idea what the difference is between a "flag" and an "option."

[pksunkara]

While the flag and option is definitely confusing (which can be improved), the default is more about modernizing the help message of cli tools with help_headings and other stuff. This has been the philosophy of clap since the beginning AFAIK.

[epage]

Could you clarify what you mean by modernizing? With clap3, we now get custom sections, which is great, but thats not exactly modern. A lot of the tools i surveyed use them. argparse has provided support for it for ... I don't remember how long. As for our default headings, its unclear what would be modern about those.

As an alternative, I could see us getting rid of all default headings and removing the flag completely. All it then takes is for someone to set their custom help headings. That aligns with what people seem to favor (with the number of people that go to the trouble of opt-ing out) while keeping it low effort to opt-in to the new custom headings feature in clap3.

[epage]

@pksunkara any update?

[epage]

I split this out into #2807

[epage]

@pksunkara

DeriveDisplayOrder should not be default because the options/subcommands in help message should be in alphabetic order which is the pattern followed by most CLI tools.

[epage]

Could you quantify which tools you surveyed when saying "most CLI tools"?

I'm going to do a broader search than I did above

Sorted

• rg
  • sort order is always respected, even for --help and --version
• tokei
  • sort order is always respected, even for --help and --version
• gnu ls
  • sort order is broken for --help / --version
• gnu df
  • sort order is broken for --help / --version
• less
  • sorts by short name, then long name (so long names without a short name are last)
  • Even sorts no- variants

Custom

• cargo
• bat
• fd
• delta
• hyperfine (I somehow missed that this was set)
• rsync
• vim
• gnu chmod
  • Even if this was sorted, I suspect the no- variants would not be sorted
• mount
• curl
• wget
• iptables
• traceroute
• gnu grep
• gnu find (mostly sorted but there are exceptions

(List of commands was inspired by prior Rust command list, some off the top of my head, and a random 50 linux command list I found. I only did a random sampling of the GNU CoreUtils though)

I previously held up rg as a tool that gets a lot of feedback. We have to also keep in mind context of that feedback. Most commands don't have many flags and, those that do, logically group them. rg is an outlier in the number of arguments it has and can't even consider using logical groups until clap3 is released (granted, there are also concerns whether in rgs case the args can be broken down into neat groups). So in this case, rg is a data point but not something to hold to, like startups shouldn't try to be "google scale" out the gate.

Also, even when non-clap commands are sorted, they make exceptions which clap doesn't allow (except for less which, because of the nature of its flag choices, didn't even need to make exceptions).

[epage]

@pksunkara any update?

[epage]

I've split this out into #2808

[joshtriplett]

In addition to those already mentioned, I'd love to have AppSettings::VersionlessSubcommands become the default. Subcommands rarely have independent version numbers; when they do, it's typically because they're an external program, in which case their own parser will want to enable --version for that external command. But for non-external subcommands, prog subcommand subsubcommand --version doesn't make much sense, and --version takes up space in the help output for that subcommand that would be better used to display more relevant options. I think most programs will only want --version for the top-level command.

[epage]

One case where someone will want this on is cargo subcommands. cargo release --version maps to cargo-release release --version. Nothing operates directly on the command. This seems like a corner case (git doesn't do this, unsure if anything else does when proxying for an external subcommand), so probably fine for those programs to opt-in,

[epage]

I do wonder if users are used to treating these arguments as global and append them to existing commands in their history. If that is the case, changing this will be a papercut for them.

This is all vaguery and is hard to know if this matters or not since people will probably live with it either way.

[joshtriplett]

@epage I completely agree that cargo needs it, at least for external subcommands.

I also wonder if it'd be a good compromise to support --version on subcommands but not show it in the help of subcommands.

[epage]

Thats an interesting compromise. I'm curious how clap handles user-defined global arguments, whether they show up in the subcommand help or not.

[epage]

Looks like we do show global args in help. This output is from a hacked up test

USAGE:
    myprog outer inner [FLAGS] [OPTIONS]

FLAGS:
        --global-flag    Specifies something needed by the subcommands
    -h, --help           Print help information
    -V, --version        Print version information

OPTIONS:
        --global-arg <GLOBAL_ARG>    Specifies something needed by the subcommands [default:
                                     default_value]

[epage]

Locking this as most conversation is moving to issues.