feat: improve cli help headers and styling (#3329)

Cargo.toml

@@ -24,7 +24,6 @@ base64 = "0.22.1"
 bytes = "1.10.0"
 chrono = "0.4.40"
 clap = { version = "4.5.31", default-features = false }
-clap-verbosity-flag = "3.0.2"
 clap_complete = "4.5.46"
 clap_complete_nushell = "4.5.5"
 concat-idents = "1.1.5"
@@ -226,7 +225,6 @@ clap = { workspace = true, features = [
   "error-context",
   "env",
 ] }
-clap-verbosity-flag = { workspace = true }
 clap_complete = { workspace = true }
 clap_complete_nushell = { workspace = true }
 console = { workspace = true, features = ["windows-console-colors"] }

crates/pixi_config/src/lib.rs

@@ -95,30 +95,30 @@ pub fn get_cache_dir() -> miette::Result<PathBuf> {
 #[derive(Parser, Debug, Default, Clone)]
 pub struct ConfigCli {
     /// Do not verify the TLS certificate of the server.
-    #[arg(long, action = ArgAction::SetTrue)]
+    #[arg(long, action = ArgAction::SetTrue, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     tls_no_verify: bool,
 
     /// Path to the file containing the authentication token.
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     auth_file: Option<PathBuf>,
 
     /// Specifies whether to use the keyring to look up credentials for PyPI.
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     pypi_keyring_provider: Option<KeyringProvider>,
 
     /// Max concurrent solves, default is the number of CPUs
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     pub concurrent_solves: Option<usize>,
 
     /// Max concurrent network requests, default is `50`
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     pub concurrent_downloads: Option<usize>,
 }
 
 #[derive(Parser, Debug, Clone, Default)]
 pub struct ConfigCliPrompt {
     /// Do not change the PS1 variable when starting a prompt.
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     change_ps1: Option<bool>,
 }
 
@@ -183,11 +183,11 @@ impl RepodataConfig {
 #[derive(Parser, Debug, Default, Clone)]
 pub struct ConfigCliActivation {
     /// Do not use the environment activation cache. (default: true except in experimental mode)
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     force_activate: bool,
 
     /// Do not source the autocompletion scripts from the environment.
-    #[arg(long)]
+    #[arg(long, help_heading = consts::CLAP_CONFIG_OPTIONS)]
     no_completion: Option<bool>,
 }
 

crates/pixi_consts/src/consts.rs

@@ -83,6 +83,9 @@ pub const ONE_TIME_MESSAGES_DIR: &str = "one-time-messages";
 pub const ENVIRONMENT_FILE_NAME: &str = "pixi";
 
 pub const RELEASES_URL: &str = "https://github.com/prefix-dev/pixi/releases";
+pub const CLAP_GLOBAL_OPTIONS: &str = "Global Options";
+pub const CLAP_CONFIG_OPTIONS: &str = "Config Options";
+pub const CLAP_GIT_OPTIONS: &str = "Git Options";
 
 pub static TASK_STYLE: LazyLock<Style> = LazyLock::new(|| Style::new().blue());
 pub static PLATFORM_STYLE: LazyLock<Style> = LazyLock::new(|| Style::new().yellow());

docs/reference/cli/pixi.md

@@ -48,13 +48,15 @@ pixi [OPTIONS] <COMMAND>
 <br>**env**: `PIXI_COLOR`
 <br>**default**: `auto`
 <br>**options**: `always`, `never`, `auto`
+- <a id="arg---help" href="#arg---help">`--help (-h)`</a>
+:  Display help information
 - <a id="arg---no-progress" href="#arg---no-progress">`--no-progress`</a>
 :  Hide all progress bars, always turned on if stderr is not a terminal
 <br>**env**: `PIXI_NO_PROGRESS`
 <br>**default**: `false`
 - <a id="arg---quiet" href="#arg---quiet">`--quiet (-q)`</a>
-:  Decrease logging verbosity
+:  Decrease logging verbosity (quiet mode)
 - <a id="arg---verbose" href="#arg---verbose">`--verbose (-v)`</a>
-:  Increase logging verbosity
+:  Increase logging verbosity (-v for warnings, -vv for info, -vvv for debug, -vvvv for trace)
 
 --8<-- "docs/reference/cli/pixi_extender.md:example"

docs/reference/cli/pixi/add.md

@@ -21,8 +21,6 @@ pixi add [OPTIONS] <SPECS>...
 :  Path to the file containing the authentication token
 - <a id="arg---branch" href="#arg---branch">`--branch <BRANCH>`</a>
 :  The git branch
-- <a id="arg---build" href="#arg---build">`--build`</a>
-:  The specified dependencies are build dependencies. Conflicts with `host` and `pypi`
 - <a id="arg---concurrent-downloads" href="#arg---concurrent-downloads">`--concurrent-downloads <CONCURRENT_DOWNLOADS>`</a>
 :  Max concurrent network requests, default is `50`
 - <a id="arg---concurrent-solves" href="#arg---concurrent-solves">`--concurrent-solves <CONCURRENT_SOLVES>`</a>
@@ -37,8 +35,6 @@ pixi add [OPTIONS] <SPECS>...
 <br>**env**: `PIXI_FROZEN`
 - <a id="arg---git" href="#arg---git">`--git (-g) <GIT>`</a>
 :  The git url to use when adding a git dependency
-- <a id="arg---host" href="#arg---host">`--host`</a>
-:  The specified dependencies are host dependencies. Conflicts with `build` and `pypi`
 - <a id="arg---locked" href="#arg---locked">`--locked`</a>
 :  Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file
 <br>**env**: `PIXI_LOCKED`

docs/reference/cli/pixi/remove.md

@@ -21,8 +21,6 @@ pixi remove [OPTIONS] <SPECS>...
 :  Path to the file containing the authentication token
 - <a id="arg---branch" href="#arg---branch">`--branch <BRANCH>`</a>
 :  The git branch
-- <a id="arg---build" href="#arg---build">`--build`</a>
-:  The specified dependencies are build dependencies. Conflicts with `host` and `pypi`
 - <a id="arg---concurrent-downloads" href="#arg---concurrent-downloads">`--concurrent-downloads <CONCURRENT_DOWNLOADS>`</a>
 :  Max concurrent network requests, default is `50`
 - <a id="arg---concurrent-solves" href="#arg---concurrent-solves">`--concurrent-solves <CONCURRENT_SOLVES>`</a>
@@ -35,8 +33,6 @@ pixi remove [OPTIONS] <SPECS>...
 <br>**env**: `PIXI_FROZEN`
 - <a id="arg---git" href="#arg---git">`--git (-g) <GIT>`</a>
 :  The git url to use when adding a git dependency
-- <a id="arg---host" href="#arg---host">`--host`</a>
-:  The specified dependencies are host dependencies. Conflicts with `build` and `pypi`
 - <a id="arg---locked" href="#arg---locked">`--locked`</a>
 :  Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file
 <br>**env**: `PIXI_LOCKED`

src/cli/cli_config.rs

@@ -28,7 +28,7 @@ use pixi_git::GIT_URL_QUERY_REV_TYPE;
 #[derive(Parser, Debug, Default, Clone)]
 pub struct WorkspaceConfig {
     /// The path to `pixi.toml`, `pyproject.toml`, or the workspace directory
-    #[arg(long, global = true)]
+    #[arg(long, global = true, help_heading = consts::CLAP_GLOBAL_OPTIONS)]
     pub manifest_path: Option<PathBuf>,
 }
 
@@ -151,15 +151,15 @@ impl PrefixUpdateConfig {
 #[derive(Parser, Debug, Default, Clone)]
 pub struct GitRev {
     /// The git branch
-    #[clap(long, requires = "git", conflicts_with_all = ["tag", "rev"])]
+    #[clap(long, requires = "git", conflicts_with_all = ["tag", "rev"], help_heading = consts::CLAP_GIT_OPTIONS)]
     pub branch: Option<String>,
 
     /// The git tag
-    #[clap(long, requires = "git", conflicts_with_all = ["branch", "rev"])]
+    #[clap(long, requires = "git", conflicts_with_all = ["branch", "rev"], help_heading = consts::CLAP_GIT_OPTIONS)]
     pub tag: Option<String>,
 
     /// The git revision
-    #[clap(long, requires = "git", conflicts_with_all = ["branch", "tag"])]
+    #[clap(long, requires = "git", conflicts_with_all = ["branch", "tag"], help_heading = consts::CLAP_GIT_OPTIONS)]
     pub rev: Option<String>,
 }
 
@@ -236,12 +236,12 @@ pub struct DependencyConfig {
 
     /// The specified dependencies are host dependencies. Conflicts with `build`
     /// and `pypi`
-    #[arg(long, conflicts_with_all = ["build", "pypi"])]
+    #[arg(long, conflicts_with_all = ["build", "pypi"], hide = true)]
     pub host: bool,
 
     /// The specified dependencies are build dependencies. Conflicts with `host`
     /// and `pypi`
-    #[arg(long, conflicts_with_all = ["host", "pypi"])]
+    #[arg(long, conflicts_with_all = ["host", "pypi"], hide = true)]
     pub build: bool,
 
     /// The specified dependencies are pypi dependencies. Conflicts with `host`
@@ -258,15 +258,15 @@ pub struct DependencyConfig {
     pub feature: FeatureName,
 
     /// The git url to use when adding a git dependency
-    #[clap(long, short)]
+    #[clap(long, short, help_heading = consts::CLAP_GIT_OPTIONS)]
     pub git: Option<Url>,
 
     #[clap(flatten)]
     /// The git revisions to use when adding a git dependency
     pub rev: Option<GitRev>,
 
     /// The subdirectory of the git repository to use
-    #[clap(long, short, requires = "git")]
+    #[clap(long, short, requires = "git", help_heading = consts::CLAP_GIT_OPTIONS)]
     pub subdir: Option<String>,
 }
 

src/cli/config.rs

@@ -45,15 +45,15 @@ enum Subcommand {
 #[derive(Parser, Debug, Clone)]
 struct CommonArgs {
     /// Operation on project-local configuration
-    #[arg(long, short, conflicts_with_all = &["global", "system"])]
+    #[arg(long, short, conflicts_with_all = &["global", "system"], help_heading = consts::CLAP_CONFIG_OPTIONS)]
     local: bool,
 
     /// Operation on global configuration
-    #[arg(long, short, conflicts_with_all = &["local", "system"])]
+    #[arg(long, short, conflicts_with_all = &["local", "system"], help_heading = consts::CLAP_CONFIG_OPTIONS)]
     global: bool,
 
     /// Operation on system configuration
-    #[arg(long, short, conflicts_with_all = &["local", "global"])]
+    #[arg(long, short, conflicts_with_all = &["local", "global"], help_heading = consts::CLAP_CONFIG_OPTIONS)]
     system: bool,
 
     #[clap(flatten)]