Debian Codegraph @

site/content/completions/zsh.md

raw
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