Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(cli): Make --help easier to browse #11905

Merged
merged 1 commit into from
Aug 8, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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(
epage marked this conversation as resolved.
Show resolved Hide resolved
"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