Add cargo help --commands

[ToBinio]

Problem

currently, the only real way to know which cargo subcommands are available is through cargo --list. However the output of cargo --list is not very clear.

b                    alias: build
bench                Execute all benchmarks of a local package
build                Compile a local package and all of its dependencies
build-man            alias: run --package xtask-build-man --
c                    alias: check

the main problems for me are:

• all types of commands (built-in commands, custom aliases, and installed commands) are in one big list
• built in commands and there aliases are visually not connected
• there is no computer-friendly way to get this information

a bit more information about these problems can be found in #12093

Proposed Solution

Adding an alternative/replacement for cargo --list. cargo help --commands this change would also make it clear what the comment does. Printing information about all possible commands.
this could then fix the before-noted problems.

example output:

Built-in commands:
    add                     Add dependencies to a Cargo.toml manifest file
    bench                   Execute all benchmarks of a local package
    build, b                Compile a local package and all of its dependencies
    ...

Custom aliases:
    build-man               run --package xtask-build-man --
    ...

Installed commands:
    clippy                  Checks a package to catch common mistakes and improve your Rust code.
    ...

Spliting types

instead of having all commands in one long list, it would split them into 3 categories.

• Built-in commands: all commands which are found in the cargo code. this would also include their aliases
• custom aliases: this would include all aliases defined by users in their settings files. and aliases which are more complex than a one-to-one mapping to another command. e.g build-man
• installed commands: all commands not found in the cargo code. mostly installed through cargo install but also pre-installed things like clippy and fmt

an example of a similar splitting behavior can be seen with git --help

aliases

instead of having aliases and their base explanation in separate lines.

like now :

b                    alias: build
bench                Execute all benchmarks of a local package
build                Compile a local package and all of its dependencies
build-man            alias: run --package xtask-build-man --
c                    alias: check

it could look more like cargo --help | default clap help

build, b     Compile the current package
check, c     Analyze the current package and report errors, but don't build object files
clean        Remove the target directory
doc, d       Build this package's and its dependencies' documentation

Other formats

instead of just the normal human readable code, it would also have support for the
--message-format flag. This would enable printing the information in a more computer-friendly way like json.

Notes

In the future, this could be expanded to extra commands for every single command category.

• cargo help --built-in-commands
• cargo help --custom-aliases
• cargo help --installed-commands

in addition, all of these commands would work with --message-format

thanks for all support / comments on #12093 by weihanglo, ehuss, epage

[epage]

all types of commands (built-in commands, custom aliases, and installed commands) are in one big list

This is listed as a problem but I feel this is more of a solution. Could you elaborate why this would be useful?

In thinking on this, another way to organize commands is by their role like at https://doc.rust-lang.org/cargo/commands/index.html

built in commands and there aliases are visually not connected

There are three tiers of aliases we need to keep in mind

• Built-in short-hand aliases (cargo b for cargo build)
• User short-hand aliases (cargo y for cargo yank)
• User complex aliases (cargo xtask for cargo run -p xtask -- )

Dealing with these makes me hesistant

[weihanglo]

There are three tiers of aliases we need to keep in mind

I think there are only two tiers – built-in and user-defined. We don't need special treatment for user short-hand aliases.

[ToBinio]

This is listed as a problem but I feel this is more of a solution. Could you elaborate why this would be useful?

I personally think the current version of cargo --list is very confusing and almost unusable especially if you have many subcommands installed. Often it is faster to google instead of using cargo --list to find the command you are searching for. Additionally, splitting them into multi categories could help new people to discover all that cargo has to offer.

In thinking on this, another way to organize commands is by their role like at https://doc.rust-lang.org/cargo/commands/index.html

does this mean you would suggest splitting the built-in commands into their separate categories? if so... I believe this would help make cargo help --comments even more usable.
Mabey then in the future there could be the possibility for installable crates to categorize themself.

[weihanglo]

The Cargo team discussed this in the triage meeting this week. We generally agree that the enhancement looks quite nice. However, we have some concerns and haven't yet made a decision. May need more info to move forward.

• The semantic of cargo help is getting help manuals. It seems a bit weird that cargo help --commands or cargo help -a retrieves a list of commands.

• cargo --list may still be worth a fix; we can have a transition period — ship the fix of shell completion script first. After 6 months or so we bump the change.

  • It's unclear how to tell people to update their shell completion scripts.
  • We cannot update shell completions scripts we don't have direct controls to (shells other than bash and zsh).
  • There is a lack of testing against shell completion in Cargo.

• We may want to expand cargo help to display guidance, e.g., cargo help dependency. However, it make the semantic of --commands flag even weirder. There are three use cases mixed here

  • machine-readable
  • human-readable, I want to know what’s there
  • human-readable, what I can get help about

  Should we put these three different things all in cargo help?

Sorry we didn't have enough time to make a decision. I am just jotting down what I can remember from the meeting.

[ToBinio]

First of all thanks for that information.

• Maybe I am missing something but I couldn't find anything about cargo help -a so what is it?

• Regarding the semantic of cargo help, I think its core functionally would fit into cargo help very well only the machine-readable part does feel a bit off. If things like cargo help dependency are coming it would probably make sense to not use a flag and instead, also make --commands to a subcommand

• Personally, I don't think the name of cargo --list tells you what it really does. Maybe instead of reworking cargo --list. cargo help --commands could be something like cargo --commands or maybe even its own subcommand cargo commands. this would solve the cargo help semantics problem and make the transition away from cargo --list simpler.

• just a random thought cargo help already shows some of the possible commands this could be extended so it shows all possible commands.

  • in that case I wouldn't be sure how to access the machine-readable data.
  • This could also add some performance overhead because instead of just having just a static text. it would need to load all the data.

i hope my quick thoughts can help a bit.

[epage]

Maybe I am missing something but I couldn't find anything about cargo help -a so what is it?

cargo help -a was used as an example of a potential command, not one that exists today. The equivalent of cargo help --commands in git is git help --all (which isn't all...)

[blyxyas]

I'll try fixing the formatting issues, as seems like it's accepted that having a big list of commands isn't very readable.

[blyxyas]

Maybe adding a --simple argument to print the old output would solve the compatibility issues.
This would only require changing scripts from one command to another.

We could use JSON as a machine readable, same as cargo metadata. Maybe with a scheme similar to this one:

{
    "name": "build",
    "type": "alias" | "external" | "builtin",
    "about": {
        "to": "<alias expanded>" | "<external path>" | undefined,
        "info": "<command info section>" | undefined
    }
}

(obviously minified)

(Note that both about.to and about.info should NEVER be undefined at the same time)

---

On the topic of adding a new command, I don't know if it's a good idea. Experienced users will continue using cargo --list without knowledge of a cargo help --commands. Adding a deprecation message would break parsing tools just as much as would re-vamping the whole output.

[Hellzbellz123]

Curious on the current status of this issue, I have a local copy of Cargo built from source with a fix that I'm trying too use but it doesn't want too play nice

If anyone knows how I can make cargo play happily with rustup I'll just keep using my local fork until this gets more attention.

[epage]

While we implement our own help subcommand, there is some general discussion on flags for help, including git's help -a at clap-rs/clap#5354