git.sr.ht/~pingoo/stdx@v0.0.0-20240218134121-094174641f6e/cobra/zsh_completions.md (about)

     1  ## Generating Zsh Completion For Your cobra.Command
     2  
     3  Please refer to [Shell Completions](shell_completions.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