Merge pull request #4056 from epage/help

fix!: Require explicit help/version disabling

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_bench/benches/05_ripgrep.rs

@@ -310,6 +310,8 @@ where
         .help_template(TEMPLATE)
         // Handle help/version manually to make their output formatting
         // consistent with short/long views.
+        .disable_help_flag(true)
+        .disable_version_flag(true)
         .arg(arg("help-short").short('h'))
         .arg(flag("help"))
         .arg(flag("version").short('V'))

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`')