Document how to source completions

[epage]

Issue by ajeetdsouza
Thursday May 20, 2021 at 05:59 GMT
Originally opened as clap-rs/clap#2488

---

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

[epage]

Comment by kidonng
Sunday Jun 20, 2021 at 16:08 GMT

---

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.

[epage]

Comment by nicholastmosher
Saturday Jul 03, 2021 at 17:22 GMT

---

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?

[epage]

Comment by kidonng
Sunday Jul 04, 2021 at 05:36 GMT

---

@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.

[epage]

Comment by nicholastmosher
Tuesday Jul 06, 2021 at 13:44 GMT

---

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 clap-rs/clap#1232