5.0 KiB
- Intro
- Getting started
- Writing your own completion functions
- Utility functions with example code
- gotchas
- Putting it all together
- Other resources
Intro
The official documentation for writing zsh completion functions is difficult to understand, and doesn't give many examples. At the time of writing this document I was able to find two other tutorials on the web, however both of those tutorials only explain a small portion of the capabilities of the completion system. This document aims to give more complete and easy to understand explanation for creating zsh completion functions. I do not go into all the details, but will give enough information and examples to get you up and running. If you need more details you can look it up for yourself in the official documentation.
Please make any scripts that you create publically available for others (e.g. by forking this repo and making a pull request).
Getting started
Telling zsh which function to use for completing a command
Completion functions for commands are stored in files with names beginning with an underscore _, and these files should be placed in a directory listed in the $fpath variable. You can add a directory to $fpath by adding a line like this to your ~/.zshrc file:
fpath=(~/newdir $fpath)The first line of a completion function file can look something like this:
#compdef foobarThis tells zsh that the file contains code for completing the foobar command. This is the format that you will use most often for the first line, but you can also use the same file for completing several different functions if you want. See here for more details.
You can also use the compdef command directly (e.g. in your ~/.zshrc file) to tell zsh which function to use for completing a command like this:
> compdef _function foobaror to use the same completions for several commands:
> compdef _function foobar goocar hoodaror if you want to supply arguments:
> compdef '_function arg1 arg2' foobarSee here for more details.
Completing generic gnu commands
Many gnu commands have a standardized way of listing option descriptions (when the –help option is used). For these commands you can use the _gnu_generic function for automatically creating completions, like this:
> compdef _gnu_generic foobaror to use _gnu_generic with several different commands:
> compdef _gnu_generic foobar goocar hoodarThis line can be placed in your ~/.zshrc file.
Copying completions from another command
If you want a command, say cmd1, to have the same completions as another, say cmd2, which has already had completions defined for it, you can do this:
> compdef cmd1=cmd2This can be useful for example if you have created an alias for a command to help you remember it.
Writing your own completion functions
A good way to get started is to look at some already defined completion functions. On my linux installation these are found in /usr/share/zsh/functions/Completion/Unix and /usr/share/zsh/functions/Completion/Linux and a few other subdirs.
You will notice that the _arguments function is used a lot in these files. This is a utility function that makes it easy to write simple completion functions. The _arguments function is a wrapper around the compadd builtin function. The compadd builtin is the core function used to add completion words to the command line, and control its behaviour. However, most of the time you will not need to use compadd, since there are many utility functions such as _arguments and _values which are easier to use.
Writing completion functions using _arguments
The _arguments function makes it easy to create completion functions. As arguments it takes special strings specifying the options & arguments to the function being completed, e.g. like this:
_arguments '--help[show help]' '-?[show help]' '1:First arg:_files'This example completes the options –help & -? when trying to complete a hyphen, which will both be listed together with the same description in this case. The first non-option argument is completed using the _files function which completes file/directories.