fix!: Require explicit help/version disabling

Before we introduced actions, it required specific setups to engage with
claps version and help printing.  With actions making that more
explicit, we don't get as much benefit from our multiple, obscure, ways
of users customizing help

Before
- Modify existing help or version with `mut_arg` which would
  automatically be pushed down the command tree like `global(true)`
- Create an new help or version and have it treated as if it was the
  built-in on (I think)
- Use the same flags as built-in and have the built-in flags
  automatically disabled
- Users could explicitly disable the built-in functionality and do what
  they want

Now
- `mut_arg` no longer works as we define help and version flags at the
  end
- If someone defines a flag that overlaps with the built-ins by id,
  long, or short, a debug assert will tell them to explicitly disable
  the built-in
- Any customization has to be done by a user providing their own.  To
  propagate through the command tree, they need to set `global(true)`.

Benefits
- Hopefully, this makes it less confusing on how to override help
  behavior.  Someone creates an arg and we then tell them how to disable
  the built-in
- This greatly simplifies the arg handling by pushing more
  responsibility onto the developer in what are hopefully just corner
  cases
- This removes about 1Kb from .text

Fixes #3405
Fixes #4033

CHANGELOG.md

@@ -35,6 +35,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Remove `Arg::use_value_delimiter` in favor of `Arg::value_delimiter`
 - Remove `Arg::require_value_delimiter`, either users could use `Arg::value_delimiter` or implement a custom parser with `TypedValueParser`
 - `ArgAction::SetTrue` and `ArgAction::SetFalse` now prioritize `Arg::default_missing_value` over their standard behavior
+- `mut_arg` can no longer be used to customize help and version arguments, instead disable them (`Command::disable_help_flag`, `Command::disable_version_flag`) and provide your own
+- `Arg::new("help")` and `Arg::new("version")` no longer implicitly disable the
+  built-in flags and be copied to all subcommands, instead disable
+  the built-in flags (`Command::disable_help_flag`,
+  `Command::disable_version_flag`) and mark the custom flags as `global(true)`.
 - *(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)

clap_complete/tests/common.rs

@@ -231,7 +231,7 @@ pub fn value_hint_command(name: &'static str) -> clap::Command<'static> {
         )
         .arg(
             clap::Arg::new("host")
-                .short('h')
+                .short('H')
                 .long("host")
                 .value_hint(clap::ValueHint::Hostname),
         )

clap_complete/tests/snapshots/aliases.bash

@@ -19,7 +19,7 @@ _my-app() {
 
     case "${cmd}" in
         my__app)
-            opts="-h -V -F -f -O -o --help --version --flg --flag --opt --option <positional>"
+            opts="-F -f -O -o -h -V --flg --flag --opt --option --help --version <positional>"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/aliases.elvish

@@ -22,14 +22,14 @@ set edit:completion:arg-completer[my-app] = {|@words|
             cand -O 'cmd option'
             cand --option 'cmd option'
             cand --opt 'cmd option'
-            cand -h 'Print help information'
-            cand --help 'Print help information'
-            cand -V 'Print version information'
-            cand --version 'Print version information'
             cand -f 'cmd flag'
             cand -F 'cmd flag'
             cand --flag 'cmd flag'
             cand --flg 'cmd flag'
+            cand -h 'Print help information'
+            cand --help 'Print help information'
+            cand -V 'Print version information'
+            cand --version 'Print version information'
         }
     ]
     $completions[$command]

clap_complete/tests/snapshots/aliases.fish

@@ -1,4 +1,4 @@
 complete -c my-app -s o -s O -l option -l opt -d 'cmd option' -r
+complete -c my-app -s f -s F -l flag -l flg -d 'cmd flag'
 complete -c my-app -s h -l help -d 'Print help information'
 complete -c my-app -s V -l version -d 'Print version information'
-complete -c my-app -s f -s F -l flag -l flg -d 'cmd flag'

clap_complete/tests/snapshots/aliases.ps1

@@ -25,14 +25,14 @@ Register-ArgumentCompleter -Native -CommandName 'my-app' -ScriptBlock {
             [CompletionResult]::new('-O', 'O', [CompletionResultType]::ParameterName, 'cmd option')
             [CompletionResult]::new('--option', 'option', [CompletionResultType]::ParameterName, 'cmd option')
             [CompletionResult]::new('--opt', 'opt', [CompletionResultType]::ParameterName, 'cmd option')
-            [CompletionResult]::new('-h', 'h', [CompletionResultType]::ParameterName, 'Print help information')
-            [CompletionResult]::new('--help', 'help', [CompletionResultType]::ParameterName, 'Print help information')
-            [CompletionResult]::new('-V', 'V', [CompletionResultType]::ParameterName, 'Print version information')
-            [CompletionResult]::new('--version', 'version', [CompletionResultType]::ParameterName, 'Print version information')
             [CompletionResult]::new('-f', 'f', [CompletionResultType]::ParameterName, 'cmd flag')
             [CompletionResult]::new('-F', 'F', [CompletionResultType]::ParameterName, 'cmd flag')
             [CompletionResult]::new('--flag', 'flag', [CompletionResultType]::ParameterName, 'cmd flag')
             [CompletionResult]::new('--flg', 'flg', [CompletionResultType]::ParameterName, 'cmd flag')
+            [CompletionResult]::new('-h', 'h', [CompletionResultType]::ParameterName, 'Print help information')
+            [CompletionResult]::new('--help', 'help', [CompletionResultType]::ParameterName, 'Print help information')
+            [CompletionResult]::new('-V', 'V', [CompletionResultType]::ParameterName, 'Print version information')
+            [CompletionResult]::new('--version', 'version', [CompletionResultType]::ParameterName, 'Print version information')
             break
         }
     })

clap_complete/tests/snapshots/aliases.zsh

@@ -19,14 +19,14 @@ _my-app() {
 '*-O+[cmd option]: : ' /
 '*--option=[cmd option]: : ' /
 '*--opt=[cmd option]: : ' /
-'*-h[Print help information]' /
-'*--help[Print help information]' /
-'*-V[Print version information]' /
-'*--version[Print version information]' /
 '*-f[cmd flag]' /
 '*-F[cmd flag]' /
 '*--flag[cmd flag]' /
 '*--flg[cmd flag]' /
+'*-h[Print help information]' /
+'*--help[Print help information]' /
+'*-V[Print version information]' /
+'*--version[Print version information]' /
 '::positional:' /
 && ret=0
 }

clap_complete/tests/snapshots/basic.bash

@@ -25,7 +25,7 @@ _my-app() {
 
     case "${cmd}" in
         my__app)
-            opts="-h -c -v --help test help"
+            opts="-c -v -h --help test help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -53,7 +53,7 @@ _my-app() {
             return 0
             ;;
         my__app__test)
-            opts="-d -h -c --help"
+            opts="-d -c -h --help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/basic.elvish

@@ -18,18 +18,18 @@ set edit:completion:arg-completer[my-app] = {|@words|
     }
     var completions = [
         &'my-app'= {
-            cand -h 'Print help information'
-            cand --help 'Print help information'
             cand -c 'c'
             cand -v 'v'
+            cand -h 'Print help information'
+            cand --help 'Print help information'
             cand test 'Subcommand'
             cand help 'Print this message or the help of the given subcommand(s)'
         }
         &'my-app;test'= {
             cand -d 'd'
+            cand -c 'c'
             cand -h 'Print help information'
             cand --help 'Print help information'
-            cand -c 'c'
         }
         &'my-app;help'= {
             cand -c 'c'

clap_complete/tests/snapshots/basic.fish

@@ -1,9 +1,9 @@
-complete -c my-app -n "__fish_use_subcommand" -s h -l help -d 'Print help information'
 complete -c my-app -n "__fish_use_subcommand" -s c
 complete -c my-app -n "__fish_use_subcommand" -s v
+complete -c my-app -n "__fish_use_subcommand" -s h -l help -d 'Print help information'
 complete -c my-app -n "__fish_use_subcommand" -f -a "test" -d 'Subcommand'
 complete -c my-app -n "__fish_use_subcommand" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
 complete -c my-app -n "__fish_seen_subcommand_from test" -s d
-complete -c my-app -n "__fish_seen_subcommand_from test" -s h -l help -d 'Print help information'
 complete -c my-app -n "__fish_seen_subcommand_from test" -s c
+complete -c my-app -n "__fish_seen_subcommand_from test" -s h -l help -d 'Print help information'
 complete -c my-app -n "__fish_seen_subcommand_from help" -s c

clap_complete/tests/snapshots/basic.ps1

@@ -21,19 +21,19 @@ Register-ArgumentCompleter -Native -CommandName 'my-app' -ScriptBlock {
 
     $completions = @(switch ($command) {
         'my-app' {
-            [CompletionResult]::new('-h', 'h', [CompletionResultType]::ParameterName, 'Print help information')
-            [CompletionResult]::new('--help', 'help', [CompletionResultType]::ParameterName, 'Print help information')
             [CompletionResult]::new('-c', 'c', [CompletionResultType]::ParameterName, 'c')
             [CompletionResult]::new('-v', 'v', [CompletionResultType]::ParameterName, 'v')
+            [CompletionResult]::new('-h', 'h', [CompletionResultType]::ParameterName, 'Print help information')
+            [CompletionResult]::new('--help', 'help', [CompletionResultType]::ParameterName, 'Print help information')
             [CompletionResult]::new('test', 'test', [CompletionResultType]::ParameterValue, 'Subcommand')
             [CompletionResult]::new('help', 'help', [CompletionResultType]::ParameterValue, 'Print this message or the help of the given subcommand(s)')
             break
         }
         'my-app;test' {
             [CompletionResult]::new('-d', 'd', [CompletionResultType]::ParameterName, 'd')
+            [CompletionResult]::new('-c', 'c', [CompletionResultType]::ParameterName, 'c')
             [CompletionResult]::new('-h', 'h', [CompletionResultType]::ParameterName, 'Print help information')
             [CompletionResult]::new('--help', 'help', [CompletionResultType]::ParameterName, 'Print help information')
-            [CompletionResult]::new('-c', 'c', [CompletionResultType]::ParameterName, 'c')
             break
         }
         'my-app;help' {

clap_complete/tests/snapshots/basic.zsh

@@ -15,10 +15,10 @@ _my-app() {
 
     local context curcontext="$curcontext" state line
     _arguments "${_arguments_options[@]}" /
-'*-h[Print help information]' /
-'*--help[Print help information]' /
 '*-c[]' /
 '(-c)*-v[]' /
+'*-h[Print help information]' /
+'*--help[Print help information]' /
 ":: :_my-app_commands" /
 "*::: :->my-app" /
 && ret=0
@@ -31,9 +31,9 @@ _my-app() {
             (test)
 _arguments "${_arguments_options[@]}" /
 '*-d[]' /
+'*-c[]' /
 '*-h[Print help information]' /
 '*--help[Print help information]' /
-'*-c[]' /
 && ret=0
 ;;
 (help)

clap_complete/tests/snapshots/feature_sample.bash

@@ -25,7 +25,7 @@ _my-app() {
 
     case "${cmd}" in
         my__app)
-            opts="-h -V -C -c --help --version --conf --config <file> first second test help"
+            opts="-C -c -h -V --conf --config --help --version <file> first second test help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/feature_sample.elvish

@@ -18,14 +18,14 @@ set edit:completion:arg-completer[my-app] = {|@words|
     }
     var completions = [
         &'my-app'= {
-            cand -h 'Print help information'
-            cand --help 'Print help information'
-            cand -V 'Print version information'
-            cand --version 'Print version information'
             cand -c 'some config file'
             cand -C 'some config file'
             cand --config 'some config file'
             cand --conf 'some config file'
+            cand -h 'Print help information'
+            cand --help 'Print help information'
+            cand -V 'Print version information'
+            cand --version 'Print version information'
             cand test 'tests things'
             cand help 'Print this message or the help of the given subcommand(s)'
         }

clap_complete/tests/snapshots/feature_sample.fish

@@ -1,6 +1,6 @@
+complete -c my-app -n "__fish_use_subcommand" -s c -s C -l config -l conf -d 'some config file'
 complete -c my-app -n "__fish_use_subcommand" -s h -l help -d 'Print help information'
 complete -c my-app -n "__fish_use_subcommand" -s V -l version -d 'Print version information'
-complete -c my-app -n "__fish_use_subcommand" -s c -s C -l config -l conf -d 'some config file'
 complete -c my-app -n "__fish_use_subcommand" -f -a "test" -d 'tests things'
 complete -c my-app -n "__fish_use_subcommand" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
 complete -c my-app -n "__fish_seen_subcommand_from test" -l case -d 'the case to test' -r

clap_complete/tests/snapshots/feature_sample.ps1

@@ -21,14 +21,14 @@ Register-ArgumentCompleter -Native -CommandName 'my-app' -ScriptBlock {
 
     $completions = @(switch ($command) {
         'my-app' {
-            [CompletionResult]::new('-h', 'h', [CompletionResultType]::ParameterName, 'Print help information')
-            [CompletionResult]::new('--help', 'help', [CompletionResultType]::ParameterName, 'Print help information')
-            [CompletionResult]::new('-V', 'V', [CompletionResultType]::ParameterName, 'Print version information')
-            [CompletionResult]::new('--version', 'version', [CompletionResultType]::ParameterName, 'Print version information')
             [CompletionResult]::new('-c', 'c', [CompletionResultType]::ParameterName, 'some config file')
             [CompletionResult]::new('-C', 'C', [CompletionResultType]::ParameterName, 'some config file')
             [CompletionResult]::new('--config', 'config', [CompletionResultType]::ParameterName, 'some config file')
             [CompletionResult]::new('--conf', 'conf', [CompletionResultType]::ParameterName, 'some config file')
+            [CompletionResult]::new('-h', 'h', [CompletionResultType]::ParameterName, 'Print help information')
+            [CompletionResult]::new('--help', 'help', [CompletionResultType]::ParameterName, 'Print help information')
+            [CompletionResult]::new('-V', 'V', [CompletionResultType]::ParameterName, 'Print version information')
+            [CompletionResult]::new('--version', 'version', [CompletionResultType]::ParameterName, 'Print version information')
             [CompletionResult]::new('test', 'test', [CompletionResultType]::ParameterValue, 'tests things')
             [CompletionResult]::new('help', 'help', [CompletionResultType]::ParameterValue, 'Print this message or the help of the given subcommand(s)')
             break

clap_complete/tests/snapshots/feature_sample.zsh

@@ -15,14 +15,14 @@ _my-app() {
 
     local context curcontext="$curcontext" state line
     _arguments "${_arguments_options[@]}" /
-'*-h[Print help information]' /
-'*--help[Print help information]' /
-'*-V[Print version information]' /
-'*--version[Print version information]' /
 '*-c[some config file]' /
 '*-C[some config file]' /
 '*--config[some config file]' /
 '*--conf[some config file]' /
+'*-h[Print help information]' /
+'*--help[Print help information]' /
+'*-V[Print version information]' /
+'*--version[Print version information]' /
 '::file -- some input file:_files' /
 '::choice:(first second)' /
 ":: :_my-app_commands" /

clap_complete/tests/snapshots/quoting.bash

@@ -40,7 +40,7 @@ _my-app() {
 
     case "${cmd}" in
         my__app)
-            opts="-h -V --help --version --single-quotes --double-quotes --backticks --backslash --brackets --expansions cmd-single-quotes cmd-double-quotes cmd-backticks cmd-backslash cmd-brackets cmd-expansions help"
+            opts="-h -V --single-quotes --double-quotes --backticks --backslash --brackets --expansions --help --version cmd-single-quotes cmd-double-quotes cmd-backticks cmd-backslash cmd-brackets cmd-expansions help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

clap_complete/tests/snapshots/quoting.elvish

@@ -18,16 +18,16 @@ set edit:completion:arg-completer[my-app] = {|@words|
     }
     var completions = [
         &'my-app'= {
-            cand -h 'Print help information'
-            cand --help 'Print help information'
-            cand -V 'Print version information'
-            cand --version 'Print version information'
             cand --single-quotes 'Can be ''always'', ''auto'', or ''never'''
             cand --double-quotes 'Can be "always", "auto", or "never"'
             cand --backticks 'For more information see `echo test`'
             cand --backslash 'Avoid ''/n'''
             cand --brackets 'List packages [filter]'
             cand --expansions 'Execute the shell command with $SHELL'
+            cand -h 'Print help information'
+            cand --help 'Print help information'
+            cand -V 'Print version information'
+            cand --version 'Print version information'
             cand cmd-single-quotes 'Can be ''always'', ''auto'', or ''never'''
             cand cmd-double-quotes 'Can be "always", "auto", or "never"'
             cand cmd-backticks 'For more information see `echo test`'

clap_complete/tests/snapshots/quoting.fish

@@ -1,11 +1,11 @@
-complete -c my-app -n "__fish_use_subcommand" -s h -l help -d 'Print help information'
-complete -c my-app -n "__fish_use_subcommand" -s V -l version -d 'Print version information'
 complete -c my-app -n "__fish_use_subcommand" -l single-quotes -d 'Can be /'always/', /'auto/', or /'never/''
 complete -c my-app -n "__fish_use_subcommand" -l double-quotes -d 'Can be "always", "auto", or "never"'
 complete -c my-app -n "__fish_use_subcommand" -l backticks -d 'For more information see `echo test`'
 complete -c my-app -n "__fish_use_subcommand" -l backslash -d 'Avoid /'//n/''
 complete -c my-app -n "__fish_use_subcommand" -l brackets -d 'List packages [filter]'
 complete -c my-app -n "__fish_use_subcommand" -l expansions -d 'Execute the shell command with $SHELL'
+complete -c my-app -n "__fish_use_subcommand" -s h -l help -d 'Print help information'
+complete -c my-app -n "__fish_use_subcommand" -s V -l version -d 'Print version information'
 complete -c my-app -n "__fish_use_subcommand" -f -a "cmd-single-quotes" -d 'Can be /'always/', /'auto/', or /'never/''
 complete -c my-app -n "__fish_use_subcommand" -f -a "cmd-double-quotes" -d 'Can be "always", "auto", or "never"'
 complete -c my-app -n "__fish_use_subcommand" -f -a "cmd-backticks" -d 'For more information see `echo test`'

clap_complete/tests/snapshots/quoting.ps1

@@ -21,16 +21,16 @@ Register-ArgumentCompleter -Native -CommandName 'my-app' -ScriptBlock {
 
     $completions = @(switch ($command) {
         'my-app' {
-            [CompletionResult]::new('-h', 'h', [CompletionResultType]::ParameterName, 'Print help information')
-            [CompletionResult]::new('--help', 'help', [CompletionResultType]::ParameterName, 'Print help information')
-            [CompletionResult]::new('-V', 'V', [CompletionResultType]::ParameterName, 'Print version information')
-            [CompletionResult]::new('--version', 'version', [CompletionResultType]::ParameterName, 'Print version information')
             [CompletionResult]::new('--single-quotes', 'single-quotes', [CompletionResultType]::ParameterName, 'Can be ''always'', ''auto'', or ''never''')
             [CompletionResult]::new('--double-quotes', 'double-quotes', [CompletionResultType]::ParameterName, 'Can be "always", "auto", or "never"')
             [CompletionResult]::new('--backticks', 'backticks', [CompletionResultType]::ParameterName, 'For more information see `echo test`')
             [CompletionResult]::new('--backslash', 'backslash', [CompletionResultType]::ParameterName, 'Avoid ''/n''')
             [CompletionResult]::new('--brackets', 'brackets', [CompletionResultType]::ParameterName, 'List packages [filter]')
             [CompletionResult]::new('--expansions', 'expansions', [CompletionResultType]::ParameterName, 'Execute the shell command with $SHELL')
+            [CompletionResult]::new('-h', 'h', [CompletionResultType]::ParameterName, 'Print help information')
+            [CompletionResult]::new('--help', 'help', [CompletionResultType]::ParameterName, 'Print help information')
+            [CompletionResult]::new('-V', 'V', [CompletionResultType]::ParameterName, 'Print version information')
+            [CompletionResult]::new('--version', 'version', [CompletionResultType]::ParameterName, 'Print version information')
             [CompletionResult]::new('cmd-single-quotes', 'cmd-single-quotes', [CompletionResultType]::ParameterValue, 'Can be ''always'', ''auto'', or ''never''')
             [CompletionResult]::new('cmd-double-quotes', 'cmd-double-quotes', [CompletionResultType]::ParameterValue, 'Can be "always", "auto", or "never"')
             [CompletionResult]::new('cmd-backticks', 'cmd-backticks', [CompletionResultType]::ParameterValue, 'For more information see `echo test`')