使用Clap为CLI子命令分组：subcommand_help_heading参数不生效

问题描述 #

尝试用Clap创建包含大量子命令的CLI，编写了如下代码，但subcommand_help_heading参数未生效，无法实现子命令按指定标题分组显示的效果：

#[derive(Parser)]
pub struct Cli {
    #[command(subcommand)]
    pub command: Commands,
}

#[derive(Subcommand)]
pub enum Commands {
    /// Determine reads mapping to sample-specific MAGs
    #[command(subcommand_help_heading = "FirstHeading")]
    Subcommand1(Subcommand1Args),

    /// Create sketches from FASTA/Q file(s)
    #[command(subcommand_help_heading = "SecondHeading")]
    Subcommand2(Subcommand2Args),
}

期望的帮助输出格式：

My command line interface.

Usage: my_program <COMMAND>

FirstHeading:
  subcommand1  ...

SecondHeading:
  subcommand2 ...

Options:
  -h, --help     Print help
  -V, --version  Print version

解决方案 #

要实现子命令分组，需要调整两个关键配置：

1. 在父命令的subcommand属性中添加grouped = true，开启子命令分组功能；
2. 将子命令变体上的subcommand_help_heading替换为help_heading，用于指定该子命令所属的分组标题。

修改后的完整代码示例：

use clap::{Parser, Subcommand, Args};

#[derive(Parser)]
#[command(about = "My command line interface.")]
pub struct Cli {
    #[command(subcommand, grouped = true)]
    pub command: Commands,
}

#[derive(Subcommand)]
pub enum Commands {
    /// Determine reads mapping to sample-specific MAGs
    #[command(help_heading = "FirstHeading")]
    Subcommand1(Subcommand1Args),

    /// Create sketches from FASTA/Q file(s)
    #[command(help_heading = "SecondHeading")]
    Subcommand2(Subcommand2Args),
}

#[derive(Args)]
pub struct Subcommand1Args {}

#[derive(Args)]
pub struct Subcommand2Args {}

原理说明 #

• subcommand_help_heading是父命令的属性，作用是设置整个子命令区块的总标题（默认值为"Commands:"），并非用于单个子命令的分组；
• 开启grouped = true后，Clap会自动识别子命令变体上的help_heading属性，将同组的子命令归类到对应标题下显示，最终得到你期望的分组格式。

内容的提问来源于stack exchange，提问作者DHP