Skip to content

Latest commit

 

History

History
72 lines (60 loc) · 3.89 KB

zsh_completions.md

File metadata and controls

72 lines (60 loc) · 3.89 KB
Raw

Generating Zsh Completion for your cobra.Command

Cobra supports native Zsh completion generated from the root cobra.Command. The generated completion script should be put somewhere in your $fpath named _<YOUR COMMAND>.

Cobra now provides a V2 version for Zsh completion. The V2 version addresses some limitations of the first version, which caused some incompatibilities between Zsh-completion and Bash-completion. Furthermore, the V2 version supports custom completions implemented using the ValidArgsFunction and RegisterFlagCompletionFunc().

To take advantage the V2 version you should use the command.GenZshCompletionV2() or command.GenZshCompletionFileV2() functions. You must provide these functions with a parameter indicating if the completions should be annotated with a description; Cobra will provide the description automatically based on usage information. You can choose to make this option configurable by your users.

The original Zsh completion (command.GenZshCompletion() or command.GenZshCompletionFile()) is retained for backwards-compatibility.

Limitations

  • Custom completions implemented in Bash scripting are not supported. You should instead use ValidArgsFunction and RegisterFlagCompletionFunc() which are supported across all shells (bash, zsh, fish).
  • Bash-completion annotations for flags are not currently supported:
    • The family of functions MarkFlag...() and MarkPersistentFlag...() which correspond to the below annotations
    • BashCompCustom (which has been superseded by RegisterFlagCompletionFunc())
    • BashCompFilenameExt (no filtering by file extension)
    • BashCompOneRequiredFlag (no required flags)
    • BashCompSubdirsInDir (no filtering by directory)
  • The Zsh-specific functions are not supported (as they are not standard across different shells):
    • MarkZshCompPositionalArgumentWords (which is superseded by ValidArgs)
    • MarkZshCompPositionalArgumentFile (no filtering of arguments by file extension)

Legacy version

The below information pertains to the legacy Zsh-completion support.

What's Supported

  • Completion for all non-hidden subcommands using their .Short description.
  • Completion for all non-hidden flags using the following rules:
    • Filename completion works by marking the flag with cmd.MarkFlagFilename... family of commands.
    • The requirement for argument to the flag is decided by the .NoOptDefVal flag value - if it's empty then completion will expect an argument.
    • Flags of one of the various *Array and *Slice types supports multiple specifications (with or without argument depending on the specific type).
  • Completion of positional arguments using the following rules:
    • Argument position for all options below starts at 1. If argument position 0 is requested it will raise an error.
    • Use command.MarkZshCompPositionalArgumentFile to complete filenames. Glob patterns (e.g. "*.log") are optional - if not specified it will offer to complete all file types.
    • Use command.MarkZshCompPositionalArgumentWords to offer specific words for completion. At least one word is required.
    • It's possible to specify completion for some arguments and leave some unspecified (e.g. offer words for second argument but nothing for first argument). This will cause no completion for first argument but words completion for second argument.
    • If no argument completion was specified for 1st argument (but optionally was specified for 2nd) and the command has ValidArgs it will be used as completion options for 1st argument.
    • Argument completions only offered for commands with no subcommands.

What's not yet Supported

  • Custom completion scripts are not supported yet (We should probably create zsh specific one, doesn't make sense to re-use the bash one as the functions will be different).
  • Whatever other feature you're looking for and doesn't exist :)