From c6fe2d4df8106986f3013bb70f1ffb062faadd6a Mon Sep 17 00:00:00 2001 From: Marc Khouzam Date: Sun, 19 Jul 2020 18:02:46 -0400 Subject: [PATCH] Improve zsh completion documentation (#1169) Signed-off-by: Marc Khouzam --- shell_completions.md | 9 +++++++-- zsh_completions.md | 1 + 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/shell_completions.md b/shell_completions.md index e0a256dd..d8416ab1 100644 --- a/shell_completions.md +++ b/shell_completions.md @@ -33,11 +33,16 @@ MacOS: Zsh: -$ source <(yourprogram completion zsh) +# If shell completion is not already enabled in your environment you will need +# to enable it. You can execute the following once: + +$ echo "autoload -U compinit; compinit" >> ~/.zshrc # To load completions for each session, execute once: $ yourprogram completion zsh > "${fpath[1]}/_yourprogram" +# You will need to start a new shell for this setup to take effect. + Fish: $ yourprogram completion fish | source @@ -363,7 +368,7 @@ Please refer to [Bash Completions](bash_completions.md) for details. Cobra supports native Zsh completion generated from the root `cobra.Command`. The generated completion script should be put somewhere in your `$fpath` and be named -`_`. +`_`. You will need to start a new shell for the completions to become available. Zsh supports descriptions for completions. Cobra will provide the description automatically, based on usage information. Cobra provides a way to completely disable such descriptions by diff --git a/zsh_completions.md b/zsh_completions.md index f432dd86..7cff6178 100644 --- a/zsh_completions.md +++ b/zsh_completions.md @@ -22,6 +22,7 @@ See further below for more details on these deprecations. |Old behavior|New behavior| |---|---| |No file completion by default (opposite of bash)|File completion by default; use `ValidArgsFunction` with `ShellCompDirectiveNoFileComp` to turn off file completion on a per-argument basis| +|Completion of flag names without the `-` prefix having been typed|Flag names are only completed if the user has typed the first `-`| `cmd.MarkZshCompPositionalArgumentFile(pos, []string{})` used to turn on file completion on a per-argument position basis|File completion for all arguments by default; `cmd.MarkZshCompPositionalArgumentFile()` is **deprecated** and silently ignored| |`cmd.MarkZshCompPositionalArgumentFile(pos, glob[])` used to turn on file completion **with glob filtering** on a per-argument position basis (zsh-specific)|`cmd.MarkZshCompPositionalArgumentFile()` is **deprecated** and silently ignored; use `ValidArgsFunction` with `ShellCompDirectiveFilterFileExt` for file **extension** filtering (not full glob filtering)| |`cmd.MarkZshCompPositionalArgumentWords(pos, words[])` used to provide completion choices on a per-argument position basis (zsh-specific)|`cmd.MarkZshCompPositionalArgumentWords()` is **deprecated** and silently ignored; use `ValidArgsFunction` to achieve the same behavior|