Document how to source completions

[ajeetdsouza]

Please complete the following tasks

• I have searched the discussions
• I have searched the existing issues

Clap Version

3.0.0-beta.2

Where?

clap_generate

What's wrong?

Currently, clap generates completions without providing any insight into how to actually get them running in the shell.

How to fix?

It would be nice if we could specify (for each shell):

1. How to source the generated completions as a file
2. How to source the generated completions when printed to stdout
3. How to add the above to your shell configuration file

[kidonng]

I'd like to give a simple and general description:

• Bash: install bash-completion (some distros have this by default), then the completions can be sourced

• Zsh: the optimal way is to use $fpath, but if one would really like to go the manual way:

  autoload -U compinit
  compinit
  source <(program completions zsh | sed '$d') # can also be `head -n -1` or whatever as long as the last line is removed
  compdef _program program

  FWIW, it is said that completions generated by cobra (clap counterpart in Go) can be directly sourced (i.e. no need to strip the last line), may worth looking into

• Fish: directly source-able 🎉

I don't have much experience with other shells so additions welcome.

[nicholastmosher]

Hmm, that makes me wonder if there wouldn't be any reason not to update the output of program completions zsh to just include the autoload and compdef commands. It'd be nice to just be able to do

source <(program completions zsh)

Where program completions zsh would just look like

autoload -U compinit
compinit
<old content of 'program completions zsh'>
compdef _program program

One could certainly do that at the app-level, but is there no reason to build that directly into the completions output of clap?

[kidonng]

@nicholastmosher I can't say for sure, but I think generally clap completions are generated at packaging time. That is to say, when you install a program from the package manager, it comes with the completions placed at the suitable location so shells will pick them up automatically. Manually sourcing the completions is not the usual way people use it.

[nicholastmosher]

Ah I see. I was taking inspiration from the oh-my-zsh kubectl completions plugin: https://github.com/ohmyzsh/ohmyzsh/blob/master/plugins/kubectl/kubectl.plugin.zsh#L1-L11, though it seems like that is more geared towards dynamic completions like described in #1232

[gakonst]

For me I had to do 2 things to get it working with ZSH 5.8 (program is your command's name):

1. Remove the last line (program "$@")
2. Replace the first line from #compdef program to #compdef _program program

Unsure why this is not happening by default, is this a bug?

Also, if there's any backticks in any help message, the shell tries to interpret it due to shell expansion, suspect it's related to #1596

[epage]

The feature=unstable-dynamic completions now have documentation on how to source them, see #5586.

I'm inclined to consider this closed but would be open to input from others on if there is concern over that vs the current code-generated completions.

[epage]

As this was resolved for dynamic completions in #5586, I'm going to go ahead and close this.

To track stabilization, see #3166