search

rust-lang / cargo

The Rust package manager
https://doc.rust-lang.org/cargo
Apache License 2.0
12.38k stars 2.35k forks source link

`cargo install --help` should mention --root more clearly #11072

Open bnoordhuis opened 1 year ago

bnoordhuis commented 1 year ago

Problem

$ cargo install --help
cargo-install 
Install a Rust binary. Default location is $HOME/.cargo/bin
<snip>

cargo tells you on the first line what the default location is but not how to override it. It is mentioned in the OPTIONS section but that's a wall of text, making it very easy to miss. It's effectively buried.

cargo help install mentions --root very clearly and I would suggest for cargo install --help to do the same.

Proposed Solution

Maybe change it to this?

Install a Rust binary. Default location is $HOME/.cargo/bin, override with --root.

Notes

No response

weihanglo commented 1 year ago

Thanks for the suggestion.

AFAIK, Cargo doesn't have the convention mentioning a specific flag in the headline of help text, and some other tools display help text inline (e.g. fish). A short summary of each command may be a better fit for that kind of tool. But you're right, the discoverability is somewhat of an issue, most subcommands favour listing global options first then their specialized ones, which might be an area to improve.

weihanglo commented 1 year ago

FWIW, cargo-add is one attempt to adopt the pattern: -h for a short briefer; --help for a longer one, and help <subcommand> is a complete reference. This approach may also help the discoverability.