Skip to content

Commit

Permalink
fix(cli): Make --help easier to browse
Browse files Browse the repository at this point in the history
This mirrors some of the categories from `cargo help` (the man pages).
There are fewer categories to avoid extra vertical space.  Instead, they
are left int the `Options` category but put first.
  • Loading branch information
epage committed Aug 8, 2023
1 parent baebd2b commit 853102f
Show file tree
Hide file tree
Showing 70 changed files with 1,040 additions and 785 deletions.
22 changes: 18 additions & 4 deletions src/bin/cargo/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -523,7 +523,9 @@ pub fn cli() -> Command {
Command::new("cargo")
// Subcommands all count their args' display order independently (from 0),
// which makes their args interspersed with global args. This puts global args last.
.next_display_order(1000)
//
// We also want these to come before auto-generated `--help`
.next_display_order(800)
.allow_external_subcommands(true)
// Doesn't mix well with our list of common cargo commands. See clap-rs/clap#3108 for
// opening clap up to allow us to style our help template
Expand Down Expand Up @@ -586,9 +588,21 @@ See 'cargo help <command>' for more information on a specific command.\n",
.value_hint(clap::ValueHint::DirPath)
.value_parser(clap::builder::ValueParser::path_buf()),
)
.arg(flag("frozen", "Require Cargo.lock and cache are up to date").global(true))
.arg(flag("locked", "Require Cargo.lock is up to date").global(true))
.arg(flag("offline", "Run without accessing the network").global(true))
.arg(
flag("frozen", "Require Cargo.lock and cache are up to date")
.help_heading(heading::MANIFEST_OPTIONS)
.global(true),
)
.arg(
flag("locked", "Require Cargo.lock is up to date")
.help_heading(heading::MANIFEST_OPTIONS)
.global(true),
)
.arg(
flag("offline", "Run without accessing the network")
.help_heading(heading::MANIFEST_OPTIONS)
.global(true),
)
.arg(multi_opt("config", "KEY=VALUE", "Override a configuration value").global(true))
.arg(
Arg::new("unstable-features")
Expand Down
2 changes: 1 addition & 1 deletion src/bin/cargo/commands/add.rs
Original file line number Diff line number Diff line change
Expand Up @@ -79,8 +79,8 @@ Example uses:
])
.arg_manifest_path()
.arg_package("Package to modify")
.arg_quiet()
.arg_dry_run("Don't actually write the manifest")
.arg_quiet()
.next_help_heading("Source")
.args([
clap::Arg::new("path")
Expand Down
31 changes: 16 additions & 15 deletions src/bin/cargo/commands/bench.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ use cargo::ops::{self, TestOptions};
pub fn cli() -> Command {
subcommand("bench")
.about("Execute all benchmarks of a local package")
.arg_quiet()
.next_display_order(0)
.arg(
Arg::new("BENCHNAME")
.action(ArgAction::Set)
Expand All @@ -16,6 +16,19 @@ pub fn cli() -> Command {
.num_args(0..)
.last(true),
)
.arg(flag("no-run", "Compile, but don't run benchmarks"))
.arg(flag(
"no-fail-fast",
"Run all benchmarks regardless of failure",
))
.arg_ignore_rust_version()
.arg_message_format()
.arg_quiet()
.arg_package_spec(
"Package to run benchmarks for",
"Benchmark all packages in the workspace",
"Exclude packages from the benchmark",
)
.arg_targets_all(
"Benchmark only this package's library",
"Benchmark only the specified binary",
Expand All @@ -28,26 +41,14 @@ pub fn cli() -> Command {
"Benchmark all benches",
"Benchmark all targets",
)
.arg(flag("no-run", "Compile, but don't run benchmarks"))
.arg_package_spec(
"Package to run benchmarks for",
"Benchmark all packages in the workspace",
"Exclude packages from the benchmark",
)
.arg_features()
.arg_jobs()
.arg_profile("Build artifacts with the specified profile")
.arg_features()
.arg_target_triple("Build for the target triple")
.arg_target_dir()
.arg_manifest_path()
.arg_ignore_rust_version()
.arg_message_format()
.arg(flag(
"no-fail-fast",
"Run all benchmarks regardless of failure",
))
.arg_unit_graph()
.arg_timings()
.arg_manifest_path()
.after_help("Run `cargo help bench` for more detailed information.\n")
}

Expand Down
15 changes: 8 additions & 7 deletions src/bin/cargo/commands/build.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,15 @@ pub fn cli() -> Command {
// subcommand aliases are handled in aliased_command()
// .alias("b")
.about("Compile a local package and all of its dependencies")
.arg_ignore_rust_version()
.arg_future_incompat_report()
.arg_message_format()
.arg_quiet()
.arg_package_spec(
"Package to build (see `cargo help pkgid`)",
"Build all packages in the workspace",
"Exclude packages from the build",
)
.arg_jobs()
.arg_targets_all(
"Build only this package's library",
"Build only the specified binary",
Expand All @@ -26,25 +28,24 @@ pub fn cli() -> Command {
"Build all benches",
"Build all targets",
)
.arg_features()
.arg_release("Build artifacts in release mode, with optimizations")
.arg_profile("Build artifacts with the specified profile")
.arg_features()
.arg_jobs()
.arg_target_triple("Build for the target triple")
.arg_target_dir()
.arg(
opt(
"out-dir",
"Copy final artifacts to this directory (unstable)",
)
.value_name("PATH"),
.value_name("PATH")
.help_heading(heading::COMPILATION_OPTIONS),
)
.arg_manifest_path()
.arg_ignore_rust_version()
.arg_message_format()
.arg_build_plan()
.arg_unit_graph()
.arg_future_incompat_report()
.arg_timings()
.arg_manifest_path()
.after_help("Run `cargo help build` for more detailed information.\n")
}

Expand Down
12 changes: 6 additions & 6 deletions src/bin/cargo/commands/check.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,15 @@ pub fn cli() -> Command {
// subcommand aliases are handled in aliased_command()
// .alias("c")
.about("Check a local package and all of its dependencies for errors")
.arg_ignore_rust_version()
.arg_future_incompat_report()
.arg_message_format()
.arg_quiet()
.arg_package_spec(
"Package(s) to check",
"Check all packages in the workspace",
"Exclude packages from the check",
)
.arg_jobs()
.arg_targets_all(
"Check only this package's library",
"Check only the specified binary",
Expand All @@ -26,17 +28,15 @@ pub fn cli() -> Command {
"Check all benches",
"Check all targets",
)
.arg_features()
.arg_jobs()
.arg_release("Check artifacts in release mode, with optimizations")
.arg_profile("Check artifacts with the specified profile")
.arg_features()
.arg_target_triple("Check for the target triple")
.arg_target_dir()
.arg_manifest_path()
.arg_ignore_rust_version()
.arg_message_format()
.arg_unit_graph()
.arg_future_incompat_report()
.arg_timings()
.arg_manifest_path()
.after_help("Run `cargo help check` for more detailed information.\n")
}

Expand Down
8 changes: 4 additions & 4 deletions src/bin/cargo/commands/clean.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ use cargo::util::print_available_packages;
pub fn cli() -> Command {
subcommand("clean")
.about("Remove artifacts that cargo has generated in the past")
.arg_doc("Whether or not to clean just the documentation directory")
.arg_quiet()
.arg_package_spec_simple("Package to clean artifacts for")
.arg_manifest_path()
.arg_target_triple("Target triple to clean output for")
.arg_target_dir()
.arg_release("Whether or not to clean release artifacts")
.arg_profile("Clean artifacts of the specified profile")
.arg_doc("Whether or not to clean just the documentation directory")
.arg_target_triple("Target triple to clean output for")
.arg_target_dir()
.arg_manifest_path()
.after_help("Run `cargo help clean` for more detailed information.\n")
}

Expand Down
22 changes: 11 additions & 11 deletions src/bin/cargo/commands/doc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,39 +7,39 @@ pub fn cli() -> Command {
// subcommand aliases are handled in aliased_command()
// .alias("d")
.about("Build a package's documentation")
.arg_quiet()
.arg(flag(
"open",
"Opens the docs in a browser after the operation",
))
.arg_package_spec(
"Package to document",
"Document all packages in the workspace",
"Exclude packages from the build",
)
.arg(flag(
"no-deps",
"Don't build documentation for dependencies",
))
.arg(flag("document-private-items", "Document private items"))
.arg_jobs()
.arg_ignore_rust_version()
.arg_message_format()
.arg_quiet()
.arg_package_spec(
"Package to document",
"Document all packages in the workspace",
"Exclude packages from the build",
)
.arg_features()
.arg_targets_lib_bin_example(
"Document only this package's library",
"Document only the specified binary",
"Document all binaries",
"Document only the specified example",
"Document all examples",
)
.arg_jobs()
.arg_release("Build artifacts in release mode, with optimizations")
.arg_profile("Build artifacts with the specified profile")
.arg_features()
.arg_target_triple("Build for the target triple")
.arg_target_dir()
.arg_manifest_path()
.arg_message_format()
.arg_ignore_rust_version()
.arg_unit_graph()
.arg_timings()
.arg_manifest_path()
.after_help("Run `cargo help doc` for more detailed information.\n")
}

Expand Down
2 changes: 1 addition & 1 deletion src/bin/cargo/commands/fetch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ pub fn cli() -> Command {
subcommand("fetch")
.about("Fetch dependencies of a package from the network")
.arg_quiet()
.arg_manifest_path()
.arg_target_triple("Fetch dependencies for the target triple")
.arg_manifest_path()
.after_help("Run `cargo help fetch` for more detailed information.\n")
}

Expand Down
52 changes: 26 additions & 26 deletions src/bin/cargo/commands/fix.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,35 @@ use cargo::ops;
pub fn cli() -> Command {
subcommand("fix")
.about("Automatically fix lint warnings reported by rustc")
.arg(flag("edition", "Fix in preparation for the next edition"))
.arg(flag(
"edition-idioms",
"Fix warnings to migrate to the idioms of an edition",
))
.arg(flag(
"broken-code",
"Fix code even if it already has compiler errors",
))
.arg(flag(
"allow-no-vcs",
"Fix code even if a VCS was not detected",
))
.arg(flag(
"allow-dirty",
"Fix code even if the working directory is dirty",
))
.arg(flag(
"allow-staged",
"Fix code even if the working directory has staged changes",
))
.arg_ignore_rust_version()
.arg_message_format()
.arg_quiet()
.arg_package_spec(
"Package(s) to fix",
"Fix all packages in the workspace",
"Exclude packages from the fixes",
)
.arg_jobs()
.arg_targets_all(
"Fix only this package's library",
"Fix only the specified binary",
Expand All @@ -24,36 +46,14 @@ pub fn cli() -> Command {
"Fix all benches",
"Fix all targets (default)",
)
.arg_features()
.arg_jobs()
.arg_release("Fix artifacts in release mode, with optimizations")
.arg_profile("Build artifacts with the specified profile")
.arg_features()
.arg_target_triple("Fix for the target triple")
.arg_target_dir()
.arg_manifest_path()
.arg_message_format()
.arg(flag(
"broken-code",
"Fix code even if it already has compiler errors",
))
.arg(flag("edition", "Fix in preparation for the next edition"))
.arg(flag(
"edition-idioms",
"Fix warnings to migrate to the idioms of an edition",
))
.arg(flag(
"allow-no-vcs",
"Fix code even if a VCS was not detected",
))
.arg(flag(
"allow-dirty",
"Fix code even if the working directory is dirty",
))
.arg(flag(
"allow-staged",
"Fix code even if the working directory has staged changes",
))
.arg_ignore_rust_version()
.arg_timings()
.arg_manifest_path()
.after_help("Run `cargo help fix` for more detailed information.\n")
}

Expand Down
4 changes: 2 additions & 2 deletions src/bin/cargo/commands/init.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@ use cargo::ops;
pub fn cli() -> Command {
subcommand("init")
.about("Create a new cargo package in an existing directory")
.arg_quiet()
.arg(Arg::new("path").action(ArgAction::Set).default_value("."))
.arg(opt("registry", "Registry to use").value_name("REGISTRY"))
.arg_new_opts()
.arg(opt("registry", "Registry to use").value_name("REGISTRY"))
.arg_quiet()
.after_help("Run `cargo help init` for more detailed information.\n")
}

Expand Down
Loading

0 comments on commit 853102f

Please sign in to comment.