1 ## Generating Zsh Completion for your cobra.Command |
1 ## Generating Zsh Completion For Your cobra.Command |
2 |
2 |
3 Cobra supports native Zsh completion generated from the root `cobra.Command`. |
3 Please refer to [Shell Completions](shell_completions.md) for details. |
4 The generated completion script should be put somewhere in your `$fpath` named |
|
5 `_<YOUR COMMAND>`. |
|
6 |
4 |
7 ### What's Supported |
5 ## Zsh completions standardization |
8 |
6 |
9 * Completion for all non-hidden subcommands using their `.Short` description. |
7 Cobra 1.1 standardized its zsh completion support to align it with its other shell completions. Although the API was kept backwards-compatible, some small changes in behavior were introduced. |
10 * Completion for all non-hidden flags using the following rules: |
|
11 * Filename completion works by marking the flag with `cmd.MarkFlagFilename...` |
|
12 family of commands. |
|
13 * The requirement for argument to the flag is decided by the `.NoOptDefVal` |
|
14 flag value - if it's empty then completion will expect an argument. |
|
15 * Flags of one of the various `*Array` and `*Slice` types supports multiple |
|
16 specifications (with or without argument depending on the specific type). |
|
17 * Completion of positional arguments using the following rules: |
|
18 * Argument position for all options below starts at `1`. If argument position |
|
19 `0` is requested it will raise an error. |
|
20 * Use `command.MarkZshCompPositionalArgumentFile` to complete filenames. Glob |
|
21 patterns (e.g. `"*.log"`) are optional - if not specified it will offer to |
|
22 complete all file types. |
|
23 * Use `command.MarkZshCompPositionalArgumentWords` to offer specific words for |
|
24 completion. At least one word is required. |
|
25 * It's possible to specify completion for some arguments and leave some |
|
26 unspecified (e.g. offer words for second argument but nothing for first |
|
27 argument). This will cause no completion for first argument but words |
|
28 completion for second argument. |
|
29 * If no argument completion was specified for 1st argument (but optionally was |
|
30 specified for 2nd) and the command has `ValidArgs` it will be used as |
|
31 completion options for 1st argument. |
|
32 * Argument completions only offered for commands with no subcommands. |
|
33 |
8 |
34 ### What's not yet Supported |
9 ### Deprecation summary |
35 |
10 |
36 * Custom completion scripts are not supported yet (We should probably create zsh |
11 See further below for more details on these deprecations. |
37 specific one, doesn't make sense to re-use the bash one as the functions will |
12 |
38 be different). |
13 * `cmd.MarkZshCompPositionalArgumentFile(pos, []string{})` is no longer needed. It is therefore **deprecated** and silently ignored. |
39 * Whatever other feature you're looking for and doesn't exist :) |
14 * `cmd.MarkZshCompPositionalArgumentFile(pos, glob[])` is **deprecated** and silently ignored. |
|
15 * Instead use `ValidArgsFunction` with `ShellCompDirectiveFilterFileExt`. |
|
16 * `cmd.MarkZshCompPositionalArgumentWords()` is **deprecated** and silently ignored. |
|
17 * Instead use `ValidArgsFunction`. |
|
18 |
|
19 ### Behavioral changes |
|
20 |
|
21 **Noun completion** |
|
22 |Old behavior|New behavior| |
|
23 |---|---| |
|
24 |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| |
|
25 |Completion of flag names without the `-` prefix having been typed|Flag names are only completed if the user has typed the first `-`| |
|
26 `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| |
|
27 |`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)| |
|
28 |`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| |
|
29 |
|
30 **Flag-value completion** |
|
31 |
|
32 |Old behavior|New behavior| |
|
33 |---|---| |
|
34 |No file completion by default (opposite of bash)|File completion by default; use `RegisterFlagCompletionFunc()` with `ShellCompDirectiveNoFileComp` to turn off file completion| |
|
35 |`cmd.MarkFlagFilename(flag, []string{})` and similar used to turn on file completion|File completion by default; `cmd.MarkFlagFilename(flag, []string{})` no longer needed in this context and silently ignored| |
|
36 |`cmd.MarkFlagFilename(flag, glob[])` used to turn on file completion **with glob filtering** (syntax of `[]string{"*.yaml", "*.yml"}` incompatible with bash)|Will continue to work, however, support for bash syntax is added and should be used instead so as to work for all shells (`[]string{"yaml", "yml"}`)| |
|
37 |`cmd.MarkFlagDirname(flag)` only completes directories (zsh-specific)|Has been added for all shells| |
|
38 |Completion of a flag name does not repeat, unless flag is of type `*Array` or `*Slice` (not supported by bash)|Retained for `zsh` and added to `fish`| |
|
39 |Completion of a flag name does not provide the `=` form (unlike bash)|Retained for `zsh` and added to `fish`| |
|
40 |
|
41 **Improvements** |
|
42 |
|
43 * Custom completion support (`ValidArgsFunction` and `RegisterFlagCompletionFunc()`) |
|
44 * File completion by default if no other completions found |
|
45 * Handling of required flags |
|
46 * File extension filtering no longer mutually exclusive with bash usage |
|
47 * Completion of directory names *within* another directory |
|
48 * Support for `=` form of flags |