feat: add command headings feature

.github/workflows/ci.yml

@@ -167,7 +167,7 @@ jobs:
     - name: Install Rust
       uses: dtolnay/rust-toolchain@stable
       with:
-        toolchain: "1.90"  # STABLE
+        toolchain: "1.91"  # STABLE
     - uses: Swatinem/rust-cache@v2
     - name: UI Tests
       run: make test-ui-${{ matrix.features }}
@@ -210,7 +210,7 @@ jobs:
     - name: Install Rust
       uses: dtolnay/rust-toolchain@stable
       with:
-        toolchain: "1.90"  # STABLE
+        toolchain: "1.91"  # STABLE
     - uses: Swatinem/rust-cache@v2
     - name: Check documentation
       env:
@@ -225,7 +225,7 @@ jobs:
     - name: Install Rust
       uses: dtolnay/rust-toolchain@stable
       with:
-        toolchain: "1.90"  # STABLE
+        toolchain: "1.91"  # STABLE
         components: rustfmt
     - uses: Swatinem/rust-cache@v2
     - name: Check formatting
@@ -239,7 +239,7 @@ jobs:
     - name: Install Rust
       uses: dtolnay/rust-toolchain@stable
       with:
-        toolchain: "1.90"  # STABLE
+        toolchain: "1.91"  # STABLE
         components: clippy
     - uses: Swatinem/rust-cache@v2
     - name: Lint (ultra-minimal)

.github/workflows/pre-commit.yml

@@ -23,7 +23,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v5
-    - uses: actions/setup-python@v5
+    - uses: actions/setup-python@v6
       with:
         python-version: '3.x'
     - uses: pre-commit/[email protected]

Makefile

@@ -10,7 +10,7 @@ ifneq (${TOOLCHAIN_TARGET},)
   ARGS+=--target ${TOOLCHAIN_TARGET}
 endif
 
-STABLE?=1.90
+STABLE?=1.91
 
 _FEATURES = minimal default wasm full debug release
 _FEATURES_minimal = --no-default-features --features "std"

clap_builder/src/builder/arg.rs

@@ -492,7 +492,7 @@ impl Arg {
     ///
     /// <div class="warning">
     ///
-    /// **NOTE:** When utilized with [`Arg::num_args(1..)`], only the **last** positional argument
+    /// **NOTE:** When utilized with [`Arg::num_args(1..)`][Arg::num_args], only the **last** positional argument
     /// may be defined as having a variable number of arguments (i.e. with the highest index)
     ///
     /// </div>
@@ -1359,7 +1359,7 @@ impl Arg {
     ///
     /// <div class="warning">
     ///
-    /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`].
+    /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`][ArgAction::Set].
     ///
     /// </div>
     ///
@@ -1487,7 +1487,7 @@ impl Arg {
     ///
     /// **WARNING:** Prior arguments with `allow_hyphen_values(true)` get precedence over known
     /// flags but known flags get precedence over the next possible positional argument with
-    /// `allow_hyphen_values(true)`.  When combined with [`Arg::num_args(..)`],
+    /// `allow_hyphen_values(true)`.  When combined with [`Arg::num_args(..)`][Arg::num_args],
     /// [`Arg::value_terminator`] is one way to ensure processing stops.
     ///
     /// </div>

clap_builder/src/builder/command.rs

@@ -27,6 +27,7 @@ use crate::output::fmt::Stream;
 use crate::output::{fmt::Colorizer, write_help, Usage};
 use crate::parser::{ArgMatcher, ArgMatches, Parser};
 use crate::util::ChildGraph;
+use crate::util::FlatSet;
 use crate::util::{color::ColorChoice, Id};
 use crate::{Error, INTERNAL_ERROR_MSG};
 
@@ -104,6 +105,7 @@ pub struct Command {
     current_disp_ord: Option<usize>,
     subcommand_value_name: Option<Str>,
     subcommand_heading: Option<Str>,
+    help_heading: Option<Option<Str>>,
     external_value_parser: Option<super::ValueParser>,
     long_help_exists: bool,
     deferred: Option<fn(Command) -> Command>,
@@ -3701,6 +3703,82 @@ impl Command {
         self.subcommand_heading = heading.into_resettable().into_option();
         self
     }
+
+    /// Set a custom help heading
+    ///
+    /// To place the `help` subcommand under a custom heading amend the default
+    /// heading using [`Command::subcommand_help_heading`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg};
+    ///   Command::new("myprog")
+    ///     .version("2.6")
+    ///     .subcommand(
+    ///        Command::new("show")
+    ///          .about("Help for show")
+    ///     )
+    ///     .print_help()
+    /// # ;
+    /// ```
+    ///
+    /// will produce
+    ///
+    /// ```text
+    /// myprog
+    ///
+    /// Usage: myprog [COMMAND]
+    ///
+    /// Commands:
+    ///     help    Print this message or the help of the given subcommand(s)
+    ///     show    Help for show
+    ///
+    /// Options:
+    ///     -h, --help       Print help
+    ///     -V, --version    Print version
+    /// ```
+    ///
+    /// but usage of `help_heading`
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg};
+    ///   Command::new("myprog")
+    ///     .version("2.6")
+    ///     .subcommand(
+    ///         Command::new("show")
+    ///             .about("Help for show")
+    ///             .help_heading("Custom heading"),
+    ///     )
+    ///     .print_help()
+    /// # ;
+    /// ```
+    ///
+    /// will produce
+    ///
+    /// ```text
+    /// myprog
+    ///
+    /// Usage: myprog [COMMAND]
+    ///
+    /// Commands:
+    ///     help    Print this message or the help of the given subcommand(s)
+    ///
+    /// Custom heading:
+    ///     show    Help for show
+    ///
+    /// Options:
+    ///     -h, --help       Print help
+    ///     -V, --version    Print version
+    /// ```
+    #[inline]
+    #[must_use]
+    pub fn help_heading(mut self, heading: impl IntoResettable<Str>) -> Self {
+        self.help_heading = Some(heading.into_resettable().into_option());
+        self
+    }
 }
 
 /// # Reflection
@@ -3940,6 +4018,15 @@ impl Command {
         self.subcommand_heading.as_deref()
     }
 
+    /// Get the help heading specified for this command, if any
+    #[inline]
+    pub fn get_help_heading(&self) -> Option<&str> {
+        self.help_heading
+            .as_ref()
+            .map(|s| s.as_deref())
+            .unwrap_or_default()
+    }
+
     /// Returns the subcommand value name.
     #[inline]
     pub fn get_subcommand_value_name(&self) -> Option<&str> {
@@ -4341,6 +4428,13 @@ impl Command {
         }
     }
 
+    #[allow(dead_code)] // overcome clippy minimal report that it is unused.
+    pub(crate) fn get_subcommand_custom_help_headings(&self) -> FlatSet<&str> {
+        self.get_subcommands()
+            .filter_map(|sc| sc.get_help_heading())
+            .collect::<FlatSet<_>>()
+    }
+
     fn _do_parse(
         &mut self,
         raw_args: &mut clap_lex::RawArgs,
@@ -5218,6 +5312,7 @@ impl Default for Command {
             current_disp_ord: Some(0),
             subcommand_value_name: Default::default(),
             subcommand_heading: Default::default(),
+            help_heading: Default::default(),
             external_value_parser: Default::default(),
             long_help_exists: false,
             deferred: None,

clap_builder/src/error/kind.rs

@@ -224,7 +224,7 @@ pub enum ErrorKind {
     /// Occurs when the user provides a value containing invalid UTF-8.
     ///
     /// To allow arbitrary data
-    /// - Set [`Arg::value_parser(value_parser!(OsString))`] for argument values
+    /// - Set [`Arg::value_parser(value_parser!(OsString))`][crate::Arg::value_parser] for argument values
     /// - Set [`Command::external_subcommand_value_parser`] for external-subcommand
     ///   values
     ///