cargo Tracking Issue for native-completion

Summary

Original issue: #6645

Documentation: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#native-completions

Testing instructions: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#native-completions

Implementation:

[x] #14493
[x] Add custom completer for cargo uninstall <TAB> (#14534)
[x] Add custom completer for cargo build --bin=<TAB> (#14533)
[x] Add custom completer for cargo build --bench=<TAB> (#14532)
[x] Add custom completer for cargo build --example=<TAB> (#14531)
[x] Add custom completer for cargo test --test=<TAB> (#14548)
[x] Add custom completer for cargo update <TAB> (#14552)
[ ] Add custom completer for cargo build --package=<TAB> (#15004, #14553)
[x] Add custom completer for cargo help <TAB> (#14557)
[x] Add custom completer for cargo -Z <TAB> (#14536)
[x] Add custom completer for cargo build --target=<TAB> (#14535)
[x] Add custom completer for cargo +<TAB> to complete toolchain name (#15301)
[x] Add custom completer for cargo <TAB> to complete aliases defined in config.toml (#15319)
[x] Add custom completer for cargo <TAB> to complete third-party subcommand names (#15961)
[ ] Completing arguments after an alias
[ ] Completing arguments after a +<toolchain>
[x] Ensure vcs, color, and message format possible values are completed (#15322)
[x] Add custom completer for cargo publish --registry=<TAB> (#14656)
[x] Add custom completer for cargo add --registry=<TAB> (#14656)
[x] Add custom completer for --features (#15309)
[x] Add completer for cargo build --manifest-path<TAB> (#15225)
[x] Add completer for cargo build --lockfile-path<TAB> (#15238)
[x] Add completer for cargo install --path<TAB> (#15266)
[x] Add completer for cargo add --path<TAB> (#15288)
[x] Registering completions / using completions with +toolchain argument
[x] #14545
[ ] Stabilize support in clap (clap-rs/clap#3166)

Unresolved Issues

[ ] Some tests are disabled on macOS.
[ ] Distinguish whether different subcommands require path fallback.
[ ] Completion candidates generation test code per completer.

Open Questions

What should we support?
- Today, cargo supports bash, zsh
- Currently, this adds fish, elvish, powershell
- rustup supports bash, fish, zsh, powershell, elvish
- Are all of sufficient quality? powershell being the biggest question
Should we add custom completer for cargo add <TAB> and cargo install <TAB> using crate.io search API

Future Extensions

Completing arguments for third-party subcommands through delegation
- Stable Cargo has supported this for both bash and zsh already.
Add custom completer for cargo <TAB> to cargo scripts
Add custom completer for cargo test <TAB> (blocked on json protocol so we can cache the names of tests)
Add custom completer for cargo build --profile=<TAB> (#15308)
Add custom completer for cargo tree --format
- Inside of {, offer each variable with closing } with a description of the variable
- Outside of {}, offer each variable inside {} with description

About tracking issues

Tracking issues are used to record the overall progress of implementation. They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions. A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature. Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Sep 09 '24 12:09 shannmu

@shannmu in testing this, some of the output isn't ideal. The new completer is respecting the documented behavior in ValueHint::Unknown which means there are cases like cargo add [TAB] that show file paths when we shouldn't. On the other hand, this is a good default for cargo install --path [TAB].

We'll need to identify places to sprinkle ValueHint::Other

Sep 18 '24 14:09 epage

Fish does a lot of parsing of Cargo output and people doing that is a reason we're careful about changing our output. It would be good to see if we could be feature parity with them and get them to switch to our completion generation.

Looking over what they do in addition to things specified

They complete --features
cargo add and cargo install complete using the crates.io search API
- This is questionable because that can disclose confidential information

See https://github.com/fish-shell/fish-shell/blob/master/share/completions/cargo.fish

Sep 18 '24 16:09 epage

We'll need to identify places to sprinkle ValueHint::Other

The file paths fallback does indeed affect the user experience. I was thinking if we could temporarily document this issue in the tracking issue. Once the main logic of the various completers is resolved, we can revisit and determine in which cases we don't need the file paths fallback and in which cases it is necessary.

Sep 18 '24 16:09 shannmu

Is there any difference in the completion of the --registry option between cargo publish and cargo add?

Oct 08 '24 09:10 shannmu

@shannmu cargo add corresponds to https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-other-registries while cargo publish --registry is https://doc.rust-lang.org/cargo/commands/cargo-publish.html#publish-options

Both are defined as coming from config, so they should be the same.

Oct 08 '24 15:10 epage

Add custom completer for cargo <TAB> to complete third-party subcommand names Add custom completer for cargo <TAB> to complete aliases defined in config.toml Add custom completer for cargo +<TAB> to complete toolchain name

This would be handled by completing the external subcommand. Support for this in clap was merged in clap-rs/clap#5706.

For the first two items, an existing place where cargo collects this information is https://github.com/rust-lang/cargo/blob/master/src/bin/cargo/main.rs#L183-L254

Jan 08 '25 15:01 epage

This CfT has been added to TWiR Issue 602.

You may now remove the call-for-testing label. Please feel free to re-add the label if you wish this CfT to appear again in a future issue.

Jun 04 '25 17:06 U007D

Just installed this into my zsh. One comment that may be unique to my personal situation. I share my zsh files across machines where I have different home directories, and sometimes across different operating systems / CPU architectures. The output of CARGO_COMPLETE=zsh cargo +nightly includes the absolute path (including home directory and host-triple) of my nightly cargo binary. I replaced it with cargo +nightly and now the same completion should work across my various machines.

Should the zsh completion do this by default rather than embedding the full local cargo binary path?

Jun 26 '25 17:06 ianloic

The setup instructions suggest putting CARGO_COMPLETE=zsh cargo +nightly in your config, instead of the output, which would keep this cross-system.

The reason we suggest this is because the interface between the output and the completions is not stable and this only requires spawning a new shell to update.

Having the direct binary path in the output helps in a couple of ways

It reduces the overhead for running the completions
The completion system doesn't allow us to customize the binary in the output. Even if it did, we likely wouldn't have enough information to do so.

Jun 26 '25 17:06 epage

Ahh yeah, I didn't want incur the overhead of running cargo for every shell I spawn. Is the long-term plan to stabilize the completion output format or keep the current approach?

Jun 26 '25 17:06 ianloic

Well actually, I just tried making my _cargo zsh autoload file the following:

#compdef cargo
source <(CARGO_COMPLETE=zsh cargo +nightly)

and that tells zsh to do the source CARGO_COMPLETE dance only once I type cargo <tab> so I don't pay a shell startup cost and I get whatever latest and greatest cargo completion happens to be on my machine.

Is it worth adding this approach to the docs?

Jun 26 '25 17:06 ianloic

Lazy loading of completions is being tracked in clap-rs/clap#5668. That will likely need to be resolved before we stabilize.

I'd like to look at the problem holistically across shells of what the workflow should be than to document a one off workaround for now.

Jun 26 '25 17:06 epage

Completing arguments for third-party subcommands through delegation

Stable Cargo has supported this for both bash and zsh already.

The original issue states this is already supported, but I want to make sure I understand what is already support and what future support may be planned.

Say I have my own cargo subcommand, cargo-foo, that I invoke as cargo foo, and I want to enable shell completions for the arguments and flags of my subcommand. Is this already supported or is support planned? For example, I'd like

cargo foo --<TAB>

To complete to the valid flags for cargo-foo.

Nov 24 '25 20:11 devjgm

The original issue states this is already supported, but I want to make sure I understand what is already support and what future support may be planned.

What do you mean that it says it is already supported? Are you referring to the quote section, second bullet?

Stable Cargo has supported this for both bash and zsh already.

I believe that is referring to work like #15247.

Nov 24 '25 20:11 epage