fix(help)!: Make DeriveDisplayOrder the default, removing it

Force sorting with `next_display_order(None)` Fixes clap-rs#2808
epage · Jul 22, 2022 · 1cf7301 · 1cf7301
1 parent 0e448c1
commit 1cf7301
Show file tree

Hide file tree

Showing 45 changed files with 954 additions and 1,039 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,11 +10,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Breaking Changes
 
 - `ErrorKind::EmptyValue` replaced with `ErrorKind::InvalidValue`
-- `ErrorKind::UnrecognizedSubcommand` replaced with `ErrorKind::InvalidSubcommand`
-- `arg!` now sets `ArgAction::SetTrue`, `ArgAction::Count`, `ArgAction::Set`, or `ArgAction::Append` as appropriate
-- *(help)* Subcommand display order respects `Command::next_display_order` instead of `DeriveDisplayOrder` and using its own initial display order value
-- *(env)* Parse `--help` and `--version` like any `ArgAction::SetTrue` flag
-- *(derive)* `subcommand_required(true).arg_required_else_help(true)` is set instead of `SubcommandRequiredElseHelp`
+- `ErrorKind::UnrecognizedSubcommand` replaced with `ErrorKind::InvalidSubcommand` (#3676)
+- `arg!` now sets `ArgAction::SetTrue`, `ArgAction::Count`, `ArgAction::Set`, or `ArgAction::Append` as appropriate (#3795)
+- *(help)* Make `DeriveDisplayOrder` the default and removed the setting.  To sort help, set `next_display_order(None)` (#2808)
+- *(help)* Subcommand display order respects `Command::next_display_order` instead of `DeriveDisplayOrder` and using its own initial display order value (#2808)
+- *(env)* Parse `--help` and `--version` like any `ArgAction::SetTrue` flag (#3776)
+- *(derive)* `subcommand_required(true).arg_required_else_help(true)` is set instead of `SubcommandRequiredElseHelp` (#3280)
 
 ### Features
 

diff --git a/clap_bench/benches/06_rustup.rs b/clap_bench/benches/06_rustup.rs
@@ -2,7 +2,7 @@
 //
 // CLI used is from rustup 408ed84f0e50511ed44a405dd91365e5da588790
 
-use clap::{AppSettings, Arg, ArgGroup, Command};
+use clap::{Arg, ArgGroup, Command};
 use criterion::{criterion_group, criterion_main, Criterion};
 
 pub fn build_rustup(c: &mut Criterion) {
@@ -26,7 +26,6 @@ fn build_cli() -> Command<'static> {
         .version("0.9.0") // Simulating
         .about("The Rust toolchain installer")
         .after_help(RUSTUP_HELP)
-        .setting(AppSettings::DeriveDisplayOrder)
         .arg(
             Arg::new("verbose")
                 .help("Enable verbose output")
@@ -67,7 +66,6 @@ fn build_cli() -> Command<'static> {
             Command::new("toolchain")
                 .about("Modify or query the installed toolchains")
                 .after_help(TOOLCHAIN_HELP)
-                .setting(AppSettings::DeriveDisplayOrder)
                 .subcommand(Command::new("list").about("List installed toolchains"))
                 .subcommand(
                     Command::new("install")
@@ -104,7 +102,6 @@ fn build_cli() -> Command<'static> {
         .subcommand(
             Command::new("target")
                 .about("Modify a toolchain's supported targets")
-                .setting(AppSettings::DeriveDisplayOrder)
                 .subcommand(
                     Command::new("list")
                         .about("List installed and available targets")
@@ -138,7 +135,6 @@ fn build_cli() -> Command<'static> {
         .subcommand(
             Command::new("component")
                 .about("Modify a toolchain's installed components")
-                .setting(AppSettings::DeriveDisplayOrder)
                 .subcommand(
                     Command::new("list")
                         .about("List installed and available components")
@@ -163,7 +159,6 @@ fn build_cli() -> Command<'static> {
             Command::new("override")
                 .about("Modify directory toolchain overrides")
                 .after_help(OVERRIDE_HELP)
-                .setting(AppSettings::DeriveDisplayOrder)
                 .subcommand(Command::new("list").about("List directory toolchain overrides"))
                 .subcommand(
                     Command::new("set")
@@ -246,7 +241,6 @@ fn build_cli() -> Command<'static> {
         .subcommand(
             Command::new("self")
                 .about("Modify the rustup installation")
-                .setting(AppSettings::DeriveDisplayOrder)
                 .subcommand(Command::new("update").about("Download and install updates to rustup"))
                 .subcommand(
                     Command::new("uninstall")
@@ -261,7 +255,6 @@ fn build_cli() -> Command<'static> {
             Command::new("telemetry")
                 .about("rustup telemetry commands")
                 .hide(true)
-                .setting(AppSettings::DeriveDisplayOrder)
                 .subcommand(Command::new("enable").about("Enable rustup telemetry"))
                 .subcommand(Command::new("disable").about("Disable rustup telemetry"))
                 .subcommand(Command::new("analyze").about("Analyze stored telemetry")),

diff --git a/examples/cargo-example-derive.md b/examples/cargo-example-derive.md
@@ -26,8 +26,8 @@ USAGE:
     cargo example-derive [OPTIONS]
 
 OPTIONS:
-    -h, --help                             Print help information
         --manifest-path <MANIFEST_PATH>    
+    -h, --help                             Print help information
     -V, --version                          Print version information
 
 ```

diff --git a/examples/cargo-example.md b/examples/cargo-example.md
@@ -26,8 +26,8 @@ USAGE:
     cargo example [OPTIONS]
 
 OPTIONS:
-    -h, --help                    Print help information
         --manifest-path <PATH>    
+    -h, --help                    Print help information
     -V, --version                 Print version information
 
 ```

diff --git a/examples/demo.md b/examples/demo.md
@@ -7,9 +7,9 @@ USAGE:
     demo[EXE] [OPTIONS] --name <NAME>
 
 OPTIONS:
+    -n, --name <NAME>      Name of the person to greet
     -c, --count <COUNT>    Number of times to greet [default: 1]
     -h, --help             Print help information
-    -n, --name <NAME>      Name of the person to greet
     -V, --version          Print version information
 
 $ demo --name Me

diff --git a/examples/derive_ref/custom-bool.md b/examples/derive_ref/custom-bool.md
@@ -14,8 +14,8 @@ ARGS:
     <BOOM>    [possible values: true, false]
 
 OPTIONS:
-        --bar <BAR>    [default: false]
         --foo <FOO>    [possible values: true, false]
+        --bar <BAR>    [default: false]
     -h, --help         Print help information
     -V, --version      Print version information
 

diff --git a/examples/derive_ref/interop_tests.md b/examples/derive_ref/interop_tests.md
@@ -107,8 +107,8 @@ USAGE:
     interop_hand_subcommand[EXE] [OPTIONS] <SUBCOMMAND>
 
 OPTIONS:
-    -h, --help         Print help information
     -t, --top-level    
+    -h, --help         Print help information
 
 SUBCOMMANDS:
     add       

diff --git a/examples/escaped-positional-derive.md b/examples/escaped-positional-derive.md
@@ -16,8 +16,8 @@ ARGS:
 
 OPTIONS:
     -f               
-    -h, --help       Print help information
     -p <PEAR>        
+    -h, --help       Print help information
     -V, --version    Print version information
 
 ```

diff --git a/examples/escaped-positional.md b/examples/escaped-positional.md
@@ -16,8 +16,8 @@ ARGS:
 
 OPTIONS:
     -f               
-    -h, --help       Print help information
     -p <PEAR>        
+    -h, --help       Print help information
     -V, --version    Print version information
 
 ```

diff --git a/examples/git-derive.md b/examples/git-derive.md
@@ -85,8 +85,8 @@ USAGE:
     git-derive[EXE] stash <SUBCOMMAND>
 
 OPTIONS:
-    -h, --help                 Print help information
     -m, --message <MESSAGE>    
+    -h, --help                 Print help information
 
 SUBCOMMANDS:
     push     
@@ -101,8 +101,8 @@ USAGE:
     git-derive[EXE] stash push [OPTIONS]
 
 OPTIONS:
-    -h, --help                 Print help information
     -m, --message <MESSAGE>    
+    -h, --help                 Print help information
 
 $ git-derive stash pop -h
 git-stash-pop 

diff --git a/examples/git.md b/examples/git.md
@@ -83,8 +83,8 @@ USAGE:
     git[EXE] stash <SUBCOMMAND>
 
 OPTIONS:
-    -h, --help                 Print help information
     -m, --message <MESSAGE>    
+    -h, --help                 Print help information
 
 SUBCOMMANDS:
     push     
@@ -99,8 +99,8 @@ USAGE:
     git[EXE] stash push [OPTIONS]
 
 OPTIONS:
-    -h, --help                 Print help information
     -m, --message <MESSAGE>    
+    -h, --help                 Print help information
 
 $ git stash pop -h
 git-stash-pop 

diff --git a/examples/multicall-busybox.md b/examples/multicall-busybox.md
@@ -31,8 +31,8 @@ USAGE:
     busybox [OPTIONS] [APPLET]
 
 OPTIONS:
-    -h, --help                 Print help information
         --install <install>    Install hardlinks for all subcommands in path
+    -h, --help                 Print help information
 
 APPLETS:
     true     does nothing successfully

diff --git a/examples/pacman.md b/examples/pacman.md
@@ -62,9 +62,9 @@ ARGS:
     <package>...    packages
 
 OPTIONS:
-    -h, --help                  Print help information
-    -i, --info                  view package information
     -s, --search <search>...    search remote repositories for matching strings
+    -i, --info                  view package information
+    -h, --help                  Print help information
 
 ```
 

diff --git a/examples/tutorial_builder/02_app_settings.rs b/examples/tutorial_builder/02_app_settings.rs
@@ -1,8 +1,7 @@
-use clap::{arg, command, AppSettings, ArgAction};
+use clap::{arg, command, ArgAction};
 
 fn main() {
     let matches = command!() // requires `cargo` feature
-        .global_setting(AppSettings::DeriveDisplayOrder)
         .allow_negative_numbers(true)
         .arg(arg!(--two <VALUE>).action(ArgAction::Set))
         .arg(arg!(--one <VALUE>).action(ArgAction::Set))

diff --git a/examples/tutorial_builder/02_apps.md b/examples/tutorial_builder/02_apps.md
@@ -8,9 +8,9 @@ USAGE:
     02_apps[EXE] --two <VALUE> --one <VALUE>
 
 OPTIONS:
-    -h, --help           Print help information
-        --one <VALUE>    
         --two <VALUE>    
+        --one <VALUE>    
+    -h, --help           Print help information
     -V, --version        Print version information
 
 $ 02_apps --version

diff --git a/examples/tutorial_builder/02_crate.md b/examples/tutorial_builder/02_crate.md
@@ -7,9 +7,9 @@ USAGE:
     02_crate[EXE] --two <VALUE> --one <VALUE>
 
 OPTIONS:
-    -h, --help           Print help information
-        --one <VALUE>    
         --two <VALUE>    
+        --one <VALUE>    
+    -h, --help           Print help information
     -V, --version        Print version information
 
 $ 02_crate --version

diff --git a/examples/tutorial_builder/03_01_flag_bool.md b/examples/tutorial_builder/03_01_flag_bool.md
@@ -7,8 +7,8 @@ USAGE:
     03_01_flag_bool[EXE] [OPTIONS]
 
 OPTIONS:
-    -h, --help       Print help information
     -v, --verbose    
+    -h, --help       Print help information
     -V, --version    Print version information
 
 $ 03_01_flag_bool

diff --git a/examples/tutorial_builder/03_01_flag_count.md b/examples/tutorial_builder/03_01_flag_count.md
@@ -7,8 +7,8 @@ USAGE:
     03_01_flag_count[EXE] [OPTIONS]
 
 OPTIONS:
-    -h, --help       Print help information
     -v, --verbose    
+    -h, --help       Print help information
     -V, --version    Print version information
 
 $ 03_01_flag_count

diff --git a/examples/tutorial_builder/03_02_option.md b/examples/tutorial_builder/03_02_option.md
@@ -7,8 +7,8 @@ USAGE:
     03_02_option[EXE] [OPTIONS]
 
 OPTIONS:
-    -h, --help           Print help information
     -n, --name <NAME>    
+    -h, --help           Print help information
     -V, --version        Print version information
 
 $ 03_02_option

diff --git a/examples/tutorial_builder/04_03_relations.md b/examples/tutorial_builder/04_03_relations.md
@@ -10,13 +10,13 @@ ARGS:
     <INPUT_FILE>    some regular input
 
 OPTIONS:
-    -c <CONFIG>                
-    -h, --help                 Print help information
+        --set-ver <VER>        set version manually
         --major                auto inc major
         --minor                auto inc minor
         --patch                auto inc patch
-        --set-ver <VER>        set version manually
         --spec-in <SPEC_IN>    some special input argument
+    -c <CONFIG>                
+    -h, --help                 Print help information
     -V, --version              Print version information
 
 $ 04_03_relations

diff --git a/examples/tutorial_builder/04_04_custom.md b/examples/tutorial_builder/04_04_custom.md
@@ -10,13 +10,13 @@ ARGS:
     <INPUT_FILE>    some regular input
 
 OPTIONS:
-    -c <CONFIG>                
-    -h, --help                 Print help information
+        --set-ver <VER>        set version manually
         --major                auto inc major
         --minor                auto inc minor
         --patch                auto inc patch
-        --set-ver <VER>        set version manually
         --spec-in <SPEC_IN>    some special input argument
+    -c <CONFIG>                
+    -h, --help                 Print help information
     -V, --version              Print version information
 
 $ 04_04_custom

diff --git a/examples/tutorial_derive/02_app_settings.rs b/examples/tutorial_derive/02_app_settings.rs
@@ -1,9 +1,8 @@
-use clap::{AppSettings, Parser};
+use clap::Parser;
 
 #[derive(Parser)]
 #[clap(author, version, about, long_about = None)]
 #[clap(allow_negative_numbers = true)]
-#[clap(global_setting(AppSettings::DeriveDisplayOrder))]
 struct Cli {
     #[clap(long, value_parser)]
     two: String,

diff --git a/examples/tutorial_derive/02_apps.md b/examples/tutorial_derive/02_apps.md
@@ -8,9 +8,9 @@ USAGE:
     02_apps[EXE] --two <VALUE> --one <VALUE>
 
 OPTIONS:
-    -h, --help           Print help information
-        --one <VALUE>    
         --two <VALUE>    
+        --one <VALUE>    
+    -h, --help           Print help information
     -V, --version        Print version information
 
 $ 02_apps --version

diff --git a/examples/tutorial_derive/02_crate.md b/examples/tutorial_derive/02_crate.md
@@ -7,9 +7,9 @@ USAGE:
     02_crate[EXE] --two <VALUE> --one <VALUE>
 
 OPTIONS:
-    -h, --help           Print help information
-        --one <VALUE>    
         --two <VALUE>    
+        --one <VALUE>    
+    -h, --help           Print help information
     -V, --version        Print version information
 
 $ 02_crate --version

diff --git a/examples/tutorial_derive/03_01_flag_bool.md b/examples/tutorial_derive/03_01_flag_bool.md
@@ -7,8 +7,8 @@ USAGE:
     03_01_flag_bool[EXE] [OPTIONS]
 
 OPTIONS:
-    -h, --help       Print help information
     -v, --verbose    
+    -h, --help       Print help information
     -V, --version    Print version information
 
 $ 03_01_flag_bool

diff --git a/examples/tutorial_derive/03_01_flag_count.md b/examples/tutorial_derive/03_01_flag_count.md
@@ -7,8 +7,8 @@ USAGE:
     03_01_flag_count[EXE] [OPTIONS]
 
 OPTIONS:
-    -h, --help       Print help information
     -v, --verbose    
+    -h, --help       Print help information
     -V, --version    Print version information
 
 $ 03_01_flag_count

diff --git a/examples/tutorial_derive/03_02_option.md b/examples/tutorial_derive/03_02_option.md
@@ -7,8 +7,8 @@ USAGE:
     03_02_option[EXE] [OPTIONS]
 
 OPTIONS:
-    -h, --help           Print help information
     -n, --name <NAME>    
+    -h, --help           Print help information
     -V, --version        Print version information
 
 $ 03_02_option

diff --git a/examples/tutorial_derive/04_03_relations.md b/examples/tutorial_derive/04_03_relations.md
@@ -10,13 +10,13 @@ ARGS:
     <INPUT_FILE>    some regular input
 
 OPTIONS:
-    -c <CONFIG>                
-    -h, --help                 Print help information
+        --set-ver <VER>        set version manually
         --major                auto inc major
         --minor                auto inc minor
         --patch                auto inc patch
-        --set-ver <VER>        set version manually
         --spec-in <SPEC_IN>    some special input argument
+    -c <CONFIG>                
+    -h, --help                 Print help information
     -V, --version              Print version information
 
 $ 04_03_relations