| 1 |
## Generating Zsh Completion For Your cobra.Command |
| 2 |
|
| 3 |
Please refer to [Shell Completions](_index.md) for details. |
| 4 |
|
| 5 |
## Zsh completions standardization |
| 6 |
|
| 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. |
| 8 |
|
| 9 |
### Deprecation summary |
| 10 |
|
| 11 |
See further below for more details on these deprecations. |
| 12 |
|
| 13 |
* `cmd.MarkZshCompPositionalArgumentFile(pos, []string{})` is no longer needed. It is therefore **deprecated** and silently ignored. |
| 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 |