display aliases in `cargo --list`

[ehuss]

It can be confusing that there are commands (aliases) available that are not displayed with cargo --list. I think displaying these can help with discovery, and make it clearer that certain commands are actually aliases.

The tricky bit is exactly how it should be exposed. There are tools and scripts that parse the output of cargo --list, which unfortunately doesn't have an explicit flag for setting the output format (such as a machine-readable format). I think something like this should work:

b                   alias: build
c                   alias: check
t                   alias: test
r                   alias: run
rr                  alias: run --release
space_example       alias: run --release -- "command list"

[CPerezz]

Hi @ehuss I would like to work on this (if possible) but I might need some help.

As far as I've seen, the only place where the aliases are listed is in src/bin/cargo/main.rs in this function.
I haven't been able to find any place in the code where this aliases are defined with a type or in a more "structured" way.

Therefore, I'm not sure if the aliases should pass to be handled more consistently (so if more of them get added, it's easier to make it happen without needing to touch strings and functions in different places) or instead, we should just edit the fn list_commands(config: &Config) -> BTreeSet<CommandInfo> and hardcore the aliases in there so they get printed with the rest of the output.

Another option is to create a list with the aliases and make the functions that interact with them point to that list.
On this way, we could edit

cargo/src/bin/cargo/cli.rs

Line 92 in f84f3f8

}

and introduce the Avaliable aliases section which will collect the data from the aliases list.

Personally, I belive it would be nice to get something like:

$ cargo --list
Installed Commands:
    bench                Execute all benchmarks of a local package
    build                Compile a local package and all of its dependencies
    check                Check a local package and all of its dependencies for errors
    clean                Remove artifacts that cargo has generated in the past
    doc                  Build a package's documentation
    fetch                Fetch dependencies of a package from the network
    fix                  Automatically fix lint warnings reported by rustc
    generate-lockfile    Generate the lockfile for a package
    git-checkout         This subcommand has been removed
    init                 Create a new cargo package in an existing directory
    install              Install a Rust binary. Default location is $HOME/.cargo/bin
    locate-project       Print a JSON representation of a Cargo.toml file's location
    login                Save an api token from the registry locally. If token is not specified, it will be read from stdin.
    metadata             Output the resolved dependencies of a package, the concrete used versions including overrides, in machine-readable format
    new                  Create a new cargo package at <path>
    owner                Manage the owners of a crate on the registry
    package              Assemble the local package into a distributable tarball
    pkgid                Print a fully qualified package specification
    publish              Upload a package to the registry
    read-manifest        Print a JSON representation of a Cargo.toml manifest.
    run                  Run a binary or example of the local package
    rustc                Compile a package, and pass extra options to the compiler
    rustdoc              Build a package's documentation, using specified custom flags.
    search               Search packages in crates.io
    test                 Execute all unit and integration tests and build examples of a local package
    tree                 Display a tree visualization of a dependency graph
    uninstall            Remove a Rust binary
    update               Update dependencies as recorded in the local lock file
    vendor               Vendor all dependencies for a project locally
    verify-project       Check correctness of crate manifest
    version              Show version information
    yank                 Remove a pushed crate from the index
Avaliable aliases:
    b                   alias: build
    c                   alias: check
    t                   alias: test
    r                   alias: run
    rr                  alias: run --release

[ehuss]

Thanks @CPerezz!

I would probably try to extract the hard-coded table (with b, c, r, t) into a separate function (or constant), so that it can be shared with the list function.

As for the output, the different headings might be nice, but since this tends to get consumed by scripts, I don't think we can add them at this time. Perhaps some time in the future a flag could be added to specify the output style, and a specifically machine-readable format could be added, giving more flexibility.

[CPerezz]

Hey @ehuss I have it working. There's only one thing I'm not sure about.

Since we use a BTreeSet for storing the commands we will print when cargo --list gets triggered as you can see in:

cargo/src/bin/cargo/main.rs

Line 77 in aa68721

let mut commands = BTreeSet::new();

we get them on this way actually:

Installed Commands:
    b                    alias: build
    bench                Execute all benchmarks of a local package
    build                Compile a local package and all of its dependencies
    c                    alias: check
    check                Check a local package and all of its dependencies for errors
    clean                Remove artifacts that cargo has generated in the past
    doc                  Build a package's documentation
    fetch                Fetch dependencies of a package from the network
    fix                  Automatically fix lint warnings reported by rustc
    generate-lockfile    Generate the lockfile for a package
    git-checkout         This subcommand has been removed
    init                 Create a new cargo package in an existing directory
    install              Install a Rust binary. Default location is $HOME/.cargo/bin
    locate-project       Print a JSON representation of a Cargo.toml file's location
    login                Save an api token from the registry locally. If token is not specified, it will be read from stdin.
    metadata             Output the resolved dependencies of a package, the concrete used versions including overrides, in machine-readable format
    new                  Create a new cargo package at <path>
    owner                Manage the owners of a crate on the registry
    package              Assemble the local package into a distributable tarball
    pkgid                Print a fully qualified package specification
    publish              Upload a package to the registry
    r                    alias: run
    read-manifest        Print a JSON representation of a Cargo.toml manifest.
    run                  Run a binary or example of the local package
    rustc                Compile a package, and pass extra options to the compiler
    rustdoc              Build a package's documentation, using specified custom flags.
    search               Search packages in crates.io
    t                    alias: test
    test                 Execute all unit and integration tests and build examples of a local package
    tree                 Display a tree visualization of a dependency graph
    uninstall            Remove a Rust binary
    update               Update dependencies as recorded in the local lock file
    vendor               Vendor all dependencies for a project locally
    verify-project       Check correctness of crate manifest
    version              Show version information
    yank                 Remove a pushed crate from the index

So the aliases and the commands are both mixed since the BTreeSet enforces the Ord.

I can think about a couple of things now:

1. Leave it as it is (not my favourite, but maybe you estimate that it's fine on this way).
2. Instead of injecting the aliases as :

for cmd in commands::builtin() {
        commands.insert(CommandInfo::BuiltIn {
            name: cmd.get_name().to_string(),
            about: cmd.p.meta.about.map(|s| s.to_string()),
        });
    }
    for command in &BUILTIN_ALIASES {
        commands.insert(CommandInfo::BuiltIn {
            name: command.0.to_string(),
            about: Some(command.1.to_string()),
        });
    }

in:

cargo/src/bin/cargo/main.rs

Line 74 in aa68721

fn list_commands(config: &Config) -> BTreeSet<CommandInfo> {

, add them later once all the prints have finnished in:

cargo/src/bin/cargo/cli.rs

Line 91 in aa68721

}

Any suggestions? Since looks like all of this aliases stuff should get a refactor and propper struct supporting so it's less tricky to work with it and expand it on the future. But I'm new to Cargo so I'm not sure at all on which is the direction you guys want to take.

[ehuss]

Hm, I don't have a strong preference either way. Whichever way appeals to you. I'm fine with it being alphabetized, and I'm also fine if you want to keep them separate. (Sorry for the non-answer! 😄 )

[CPerezz]

The code will be easier to read and all in one file if we stay with this solution.

But at some point in the future I believe a refactor will be needed in order to make easier and more readable the interaction with builtin aliases.

Thanks!! Pushing the PR then!

[ehuss]

Reopening since the intent was to show all aliases. #8542 implemented for built-in aliases. @CPerezz indicated they may be able to follow up to also include user aliases.