Make `cargo --list` combine commands and their aliases

[ToBinio]

Problem

Currently cargo --list splits the command itself and its aliase in seperate lines

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

Proposed Solution

i would say this should be changed to a simular / the same system as clap has.
combining the command and its aliase

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

this behavior can already be seen in cargo --help

Notes

No response

[weihanglo]

As you can see, Cargo provides the ability to define custom aliases.

build-man            alias: run --package xtask-build-man --

If we put the alias side by side on the same line of the original command name, it might be a bit confusing seeing other custom aliases shows on their own lines.

I would suggest the followings

• Move built-in aliases to the same line as you suggested.
• Add a new section “User-defined aliases” and display all custom aliases there.

Installed 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
    ...

User-defined aliases:
    build-man            alias: run --package xtask-build-man --
    ...

Some pointers:

• The code collecting commands and aliases. We may split it into two functions, list_commands and list_aliases.

  cargo/src/bin/cargo/main.rs

  Line 87 in e2d1488

  fn list_commands(config: &Config) -> BTreeMap<String, CommandInfo> {

• Constants of built-in aliases. This may need some refactors if we merge their displays into their built-in command counterparts. Nee

  cargo/src/bin/cargo/main.rs

  Line 43 in e2d1488

  const BUILTIN_ALIASES: [(&str, &str, &str); 6] = [

[weihanglo]

git help --all is a good reference btw.

[ToBinio]

what do you think about also spitting commands installed through cargo install into their own separate section?

then there would be 'Built-In commands', 'User-defined aliases', and 'Installed commands'

[weihanglo]

Sounds good to me!

[ToBinio]

I would like to try implementing this my self.

is there anything else I should do first / pay attention to?

[weihanglo]

You can use @rustbot claim to assign this issue to yourself. See https://github.com/rust-lang/triagebot/wiki/Assignment.

Feel free to hack it. If you have any question, ask here, open a topic on T-cargo, or ping me on Zulip.

[ToBinio]

@rustbot claim

[ehuss]

Just beware that there are tools which parse the output of --list. For example, shell completions (bash) will use it to know which commands exist. Although it is probably ill-advised to parse a human-readable output, since it has had such a simple and well-structured form for so long, and no alternatives with a machine-readable format, there will likely be various things that try to parse it.

I think we need to be careful with making too extreme of changes. Some suggestions:

1. Test things like the bash/zsh/fish completions. How badly will they be broken? Can they be easily fixed?
2. Consider keeping the changes minimal to reduce the impact.
3. Are there use cases other than shell-completions? Try some code searches to see if you can find other examples.
4. Consider what it would take to support a machine-readable format to give an alternative to tools which need to discover this information. How hard would it be to create a format that we could agree to use? It seems like an extensible format shouldn't be too hard to make.