doc: Update instructions on using native-completions

[PRO-2684]

~/.local/share/bash-completion/completions/cargo is more sensible, and recommended by rustup.

[rustbot]

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[epage]

I'm not too familiar with how the different completion locations are loaded.

So you are saying the following ~/.local/share/bash-completion/completions/cargo will work:

source <(CARGO_COMPLETE=bash cargo +nightly)

Have you tested this?

Its important to note that we are not telling people to

$ CARGO_COMPLETE=bash cargo +nightly > ~/.local/share/bash-completion/completions/cargo

And speaking of rustup, why does it have you append to the file? That seems bad if the person forgets and does it again

[epage]

Hmm, looking into that documentation in rustup, it is to conform to https://github.com/scop/bash-completion/blob/main/README.md

My question would then be how often is that installed and used?

[weihanglo]

Or make it XDG_DATA_HOME, which

• bash-completion recommends: https://github.com/scop/bash-completion/blob/89aa18b15462f117c20cde5f71e109c2f616bb62/README.md?plain=1#L153-L161
• We already did that for fish:

  cargo/src/doc/src/reference/unstable.md

  Lines 1824 to 1828 in 8b5c351

  	- fish:
  	Add `source (CARGO_COMPLETE=fish cargo +nightly | psub)` to `$XDG_CONFIG_HOME/fish/completions/cargo.fish`
  	- elvish:
  	Add `eval (E:CARGO_COMPLETE=elvish cargo +nightly | slurp)` to `$XDG_CONFIG_HOME/elvish/rc.elv`

[PRO-2684]

Or make it XDG_DATA_HOME

Maybe some fallback method should be mentioned, in case the env var doesn't exist?

[PRO-2684]

According to the code, the .local/share directory will be used as a fallback for XDG_DATA_HOME.

[weihanglo]

The suggested fallback of XDG_DATA_HOME is exactly $HOME/.local/share. I think saying XDG_DATA_HOME is good enough, alike elvish and fish.

https://specifications.freedesktop.org/basedir-spec/latest/#variables

[PRO-2684]

Have you tested this?

I've tested it on Ubuntu 24.04.2 LTS, with bash 5.2.21 and bash-completion 2.11-8.

[PRO-2684]

And speaking of rustup, why does it have you append to the file? That seems bad if the person forgets and does it again

Regarding that they used > in zsh, I suspect it's a typo.