Skip to content

Commit a460100

Browse files
epageepage
committed
feat(help): Add styling to help output
Traditionally, cargo has disabled clap's styled help output. My assumed reason is that cargo mixes custom help output with auto-generated and you couldn't previously make it all styled to match. Clap 4.2 allowed users to pass in strings styled using ANSI escape codes, allowing us to pass in styled text that matches clap, unblocking this. In clap 4.4.1, clap gained the ability for the user to override the style, allowing us to choose the styling as we wish. In this PR, I decided to use the new 4.4.1 feature to style clap's output to match the rest of cargo's output. Alternatively, we could use a more subdue style that clap uses by default. That subdued style was mostly chosen to be app theme neurtral (since we didn't have theming support yet) and there were problems with our style and no one stepped up to fix them (cargo has a style we can match to instead). I decided to *not* style `Arg::help` messages because - It might be distracting to have the descriptions lit up like a christmas tree - It is a lot more work The one exception I made was for `--list` since it is for a psuedo-command (`...`) and I wanted to intentionally draw attention to it.
1 parent 99bf036 commit a460100

38 files changed

+174
-75
lines changed

‎Cargo.lock‎

Lines changed: 22 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ cargo-test-support = { path = "crates/cargo-test-support" }
3030
cargo-util = { version = "0.2.6", path = "crates/cargo-util" }
3131
cargo_metadata = "0.14.0"
3232
clap = "4.4.1"
33+
color-print = "0.3.4"
3334
core-foundation = { version = "0.9.3", features = ["mac_os_10_7_support"] }
3435
crates-io = { version = "0.39.0", path = "crates/crates-io" }
3536
criterion = { version = "0.5.1", features = ["html_reports"] }
@@ -130,6 +131,7 @@ cargo-credential-libsecret.workspace = true
130131
cargo-credential-macos-keychain.workspace = true
131132
cargo-credential-wincred.workspace = true
132133
cargo-util.workspace = true
134+
color-print.workspace = true
133135
clap = { workspace = true, features = ["wrap_help"] }
134136
crates-io.workspace = true
135137
curl = { workspace = true, features = ["http2"] }

‎src/bin/cargo/cli.rs‎

Lines changed: 40 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -516,53 +516,64 @@ pub fn cli() -> Command {
516516
#[allow(clippy::disallowed_methods)]
517517
let is_rustup = std::env::var_os("RUSTUP_HOME").is_some();
518518
let usage = if is_rustup {
519-
"cargo [+toolchain] [OPTIONS] [COMMAND]\n cargo [+toolchain] [OPTIONS] -Zscript <MANIFEST_RS> [ARGS]..."
519+
color_print::cstr!("<blue,bold>cargo</> <blue>[+toolchain] [OPTIONS] [COMMAND]</>\n <blue,bold>cargo</> <blue>[+toolchain] [OPTIONS]</> <blue,bold>-Zscript</> <blue><<MANIFEST_RS>> [ARGS]...</>")
520520
} else {
521-
"cargo [OPTIONS] [COMMAND]\n cargo [OPTIONS] -Zscript <MANIFEST_RS> [ARGS]..."
521+
color_print::cstr!("<blue,bold>cargo</> <blue>[OPTIONS] [COMMAND]</>\n <blue,bold>cargo</> <blue>[OPTIONS]</> <blue,bold>-Zscript</> <blue><<MANIFEST_RS>> [ARGS]...</>")
522522
};
523+
524+
let styles = {
525+
use clap::builder::styling::*;
526+
Styles::styled()
527+
.header(AnsiColor::Green.on_default() | Effects::BOLD)
528+
.usage(AnsiColor::Green.on_default() | Effects::BOLD)
529+
.literal(AnsiColor::Blue.on_default() | Effects::BOLD)
530+
.placeholder(AnsiColor::Cyan.on_default())
531+
.error(AnsiColor::Red.on_default())
532+
.valid(AnsiColor::Blue.on_default() | Effects::BOLD)
533+
.invalid(AnsiColor::Yellow.on_default())
534+
};
535+
523536
Command::new("cargo")
524537
// Subcommands all count their args' display order independently (from 0),
525538
// which makes their args interspersed with global args. This puts global args last.
526539
//
527540
// We also want these to come before auto-generated `--help`
528541
.next_display_order(800)
529542
.allow_external_subcommands(true)
530-
// Doesn't mix well with our list of common cargo commands. See clap-rs/clap#3108 for
531-
// opening clap up to allow us to style our help template
532-
.disable_colored_help(true)
543+
.styles(styles)
533544
// Provide a custom help subcommand for calling into man pages
534545
.disable_help_subcommand(true)
535546
.override_usage(usage)
536-
.help_template(
547+
.help_template(color_print::cstr!(
537548
"\
538549
Rust's package manager
539550
540-
Usage: {usage}
551+
<green,bold>Usage:</> {usage}
541552
542-
Options:
553+
<green,bold>Options:</>
543554
{options}
544555
545-
Commands:
546-
build, b Compile the current package
547-
check, c Analyze the current package and report errors, but don't build object files
548-
clean Remove the target directory
549-
doc, d Build this package's and its dependencies' documentation
550-
new Create a new cargo package
551-
init Create a new cargo package in an existing directory
552-
add Add dependencies to a manifest file
553-
remove Remove dependencies from a manifest file
554-
run, r Run a binary or example of the local package
555-
test, t Run the tests
556-
bench Run the benchmarks
557-
update Update dependencies listed in Cargo.lock
558-
search Search registry for crates
559-
publish Package and upload this package to the registry
560-
install Install a Rust binary. Default location is $HOME/.cargo/bin
561-
uninstall Uninstall a Rust binary
562-
... See all commands with --list
563-
564-
See 'cargo help <command>' for more information on a specific command.\n",
565-
)
556+
<green,bold>Commands:</>
557+
<blue,bold>build</>, <blue,bold>b</> Compile the current package
558+
<blue,bold>check</>, <blue,bold>c</> Analyze the current package and report errors, but don't build object files
559+
<blue,bold>clean</> Remove the target directory
560+
<blue,bold>doc</>, <blue,bold>d</> Build this package's and its dependencies' documentation
561+
<blue,bold>new</> Create a new cargo package
562+
<blue,bold>init</> Create a new cargo package in an existing directory
563+
<blue,bold>add</> Add dependencies to a manifest file
564+
<blue,bold>remove</> Remove dependencies from a manifest file
565+
<blue,bold>run</>, <blue,bold>r</> Run a binary or example of the local package
566+
<blue,bold>test</>, <blue,bold>t</> Run the tests
567+
<blue,bold>bench</> Run the benchmarks
568+
<blue,bold>update</> Update dependencies listed in Cargo.lock
569+
<blue,bold>search</> Search registry for crates
570+
<blue,bold>publish</> Package and upload this package to the registry
571+
<blue,bold>install</> Install a Rust binary. Default location is $HOME/.cargo/bin
572+
<blue,bold>uninstall</> Uninstall a Rust binary
573+
<blue>...</> See all commands with <blue,bold>--list</>
574+
575+
See '<blue,bold>cargo help <<command>></>' for more information on a specific command.\n",
576+
))
566577
.arg(flag("version", "Print version info and exit").short('V'))
567578
.arg(flag("list", "List installed commands"))
568579
.arg(

‎src/bin/cargo/commands/add.rs‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,12 @@ pub fn cli() -> Command {
1818
clap::Command::new("add")
1919
.about("Add dependencies to a Cargo.toml manifest file")
2020
.override_usage(
21-
"\
22-
cargo add [OPTIONS] <DEP>[@<VERSION>] ...
23-
cargo add [OPTIONS] --path <PATH> ...
24-
cargo add [OPTIONS] --git <URL> ..."
25-
)
26-
.after_help("Run `cargo help add` for more detailed information.\n")
21+
color_print::cstr!("\
22+
<blue,bold>cargo add</> <blue>[OPTIONS] <<DEP>>[@<<VERSION>>] ...</>
23+
<blue,bold>cargo add</> <blue>[OPTIONS]</> <blue,bold>--path</> <blue><<PATH>> ...</>
24+
<blue,bold>cargo add</> <blue>[OPTIONS]</> <blue,bold>--git</> <blue><<URL>> ...</>"
25+
))
26+
.after_help(color_print::cstr!("Run `<blue,bold>cargo help add</>` for more detailed information.\n"))
2727
.group(clap::ArgGroup::new("selected").multiple(true).required(true))
2828
.args([
2929
clap::Arg::new("crates")

‎src/bin/cargo/commands/bench.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,9 @@ pub fn cli() -> Command {
5050
.arg_unit_graph()
5151
.arg_timings()
5252
.arg_manifest_path()
53-
.after_help("Run `cargo help bench` for more detailed information.\n")
53+
.after_help(color_print::cstr!(
54+
"Run `<blue,bold>cargo help bench</>` for more detailed information.\n"
55+
))
5456
}
5557

5658
pub fn exec(config: &mut Config, args: &ArgMatches) -> CliResult {

‎src/bin/cargo/commands/build.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,9 @@ pub fn cli() -> Command {
4646
.arg_unit_graph()
4747
.arg_timings()
4848
.arg_manifest_path()
49-
.after_help("Run `cargo help build` for more detailed information.\n")
49+
.after_help(color_print::cstr!(
50+
"Run `<blue,bold>cargo help build</>` for more detailed information.\n"
51+
))
5052
}
5153

5254
pub fn exec(config: &mut Config, args: &ArgMatches) -> CliResult {

‎src/bin/cargo/commands/check.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,9 @@ pub fn cli() -> Command {
3737
.arg_unit_graph()
3838
.arg_timings()
3939
.arg_manifest_path()
40-
.after_help("Run `cargo help check` for more detailed information.\n")
40+
.after_help(color_print::cstr!(
41+
"Run `<blue,bold>cargo help check</>` for more detailed information.\n"
42+
))
4143
}
4244

4345
pub fn exec(config: &mut Config, args: &ArgMatches) -> CliResult {

‎src/bin/cargo/commands/clean.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,9 @@ pub fn cli() -> Command {
1414
.arg_target_triple("Target triple to clean output for")
1515
.arg_target_dir()
1616
.arg_manifest_path()
17-
.after_help("Run `cargo help clean` for more detailed information.\n")
17+
.after_help(color_print::cstr!(
18+
"Run `<blue,bold>cargo help clean</>` for more detailed information.\n"
19+
))
1820
}
1921

2022
pub fn exec(config: &mut Config, args: &ArgMatches) -> CliResult {

‎src/bin/cargo/commands/doc.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,9 @@ pub fn cli() -> Command {
4040
.arg_unit_graph()
4141
.arg_timings()
4242
.arg_manifest_path()
43-
.after_help("Run `cargo help doc` for more detailed information.\n")
43+
.after_help(color_print::cstr!(
44+
"Run `<blue,bold>cargo help doc</>` for more detailed information.\n"
45+
))
4446
}
4547

4648
pub fn exec(config: &mut Config, args: &ArgMatches) -> CliResult {

‎src/bin/cargo/commands/fetch.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,9 @@ pub fn cli() -> Command {
99
.arg_quiet()
1010
.arg_target_triple("Fetch dependencies for the target triple")
1111
.arg_manifest_path()
12-
.after_help("Run `cargo help fetch` for more detailed information.\n")
12+
.after_help(color_print::cstr!(
13+
"Run `<blue,bold>cargo help fetch</>` for more detailed information.\n"
14+
))
1315
}
1416

1517
pub fn exec(config: &mut Config, args: &ArgMatches) -> CliResult {

0 commit comments

Comments
 (0)