Proposal: Better shell completions

[ehuss]

This is a proposal to add better shell completion support to Cargo. The outline of the strategy is:

• Add a cargo completions subcommand to assist with completion support.
• cargo completions <shell> will output a completion script for the given shell (bash, zsh, etc.).
• The completion script will execute cargo completions to implement the work of actually emitting completions. This can significantly simplify the work of supporting completions for different shells. The completion script is very small (see npm completion for an example). This also means all the logic can be written in one language (Rust) and can be more easily tested.

Benefits:

• Support richer completions (such as --bin or --example completing the target name).
• Maintain consistent completions across shells.
• Easier to test.
• (Maybe) easier to keep in sync with clap.
• More easily discoverable (who knows the completions even exist?).
• Completions automatically stay in sync with the release via rustup.

Drawbacks:

• More stuff to maintain.
• Minor performance drawback compared to native-shell code. Many of the existing completions already execute commands, so in many cases it is a wash. Cargo's launch speed isn't terrible (~50ms for me).
• Won't be backwards compatible with older versions of Cargo.

Please let me know if you have any thoughts or objections.

[nrc]

cargo completions <shell> will output a completion script for the given shell (bash, zsh, etc.)

I don't know how this works at all, but why do some tool's shell completions just work (e.g., Git) whereas the Rust tools seem to need some kind of opt-in step? Of course, I think it would be nice if we didn't need this opt-in step.

[ehuss]

didn't need this opt-in step

It depends on how rust/cargo is installed. Some installers (like ubuntu) will automatically add the completion file to the global location (such as /usr/share/bash-completion/completions/) and it will "just work" assuming your shell is configured to load them. rustup does not do that, since it avoids touching files outside of the user's home directory. rustup could install them in the user's home directory ($XDG_DATA_HOME/bash-completion/completions, and probably something similar for other shells). That would need to be a decision for rustup to make, if it is acceptable to dump files in various locations.

[jpalomaki]

FWIW, I just started learning Rust (cargo), using rustup, and this was pretty much the first thing I hit. 😄

If we want to keep stuff in the user's home directory (as opposed to e.g. /etc/bash_completion.d), one way to do this (for bash) is:

echo 'source <(cargo completion bash)' >> ~/.bashrc

I use said approach with kubectl: https://kubernetes.io/docs/tasks/tools/install-kubectl/#enabling-shell-autocompletion

[scooter-dangle]

@ehuss, had you considered looking at how to include something like this in clap (or as an add-on to clap) rather than directly in cargo?

[ehuss]

@scooter-dangle In a sense, it will be a clap addon, because it will probably be looking at the (hidden) clap internals to infer the options. My impression is that clap development has stalled and v3 has a long ways to go, so I don't think it is something we can use in the foreseeable future, and there's no indication how new features like this would make progress. There is an issue for this (clap-rs/clap#810), but there's no sense from the issue if it will support custom extensions or how it will work.

[andradei]

I used rustup completions zsh cargo and it is not working. Thanks for the work on this.

Related issue: rust-lang/rustup#1821

[tesuji]

See more:

• https://docs.rs/clap/2.33.0/clap/struct.App.html#method.gen_completions_to
• Example from rustup: https://github.com/rust-lang/rustup.rs/blob/136e0c47bc3ff5b5212a24bece8ce4547ed5bcfa/src/cli/rustup_mode.rs#L1192-L1213
• The rustup PR that added it: Completions rustup#773

[pickfire]

Is it possible to reduce cargo start time or optionally use generated completions as it is faster only a one-time cost?

[ehuss]

Is it possible to reduce cargo start time

I'm not sure what you mean here. Cargo should launch in about 25ms, depending on your system. I think that should be plenty fast for completion.

[hsandt]

As a workaround, for now I just added a symlink to the installed completions for my current toolchain, in my local completions. On Linux, stable toolchain:

$ ln -s ~/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/etc/bash_completion.d/cargo ~/.local/share/bash-completion/completions/cargo

This will work for a specific toolchain, but the file seems to be a copy of cargo.bashcomp.sh, so I guess it doesn't matter too much.