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

Author: epage

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'