zsh-completions/zsh-completions-howto.org

• Intro
• Getting started
  • Telling zsh which function to use for completing a command
  • Completing generic gnu commands
  • Copying completions from another command
• Writing your own completion functions
  • Utility functions
    • main utility functions for overall completion
    • functions for performing complex completions
    • functions for completing specific types of objects
    • other functions
  • Writing completion functions using _arguments
  • Actions
    • Examples
  • Patterns
  • Writing completion functions using _values
  • Functions for completing specific types of objects
• Utility functions with example code
  • compadd
  • _gnu_generic
  • _arguments
  • _regex_arguments
  • _regex_words
  • _values
  • _comma_separated
  • _files
  • _net_interfaces
• testing & debugging
• 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 a few other tutorials on the web, however those tutorials only explain a small portion of the capabilities of the completion system. This document aims to cover areas not explained elsewhere, with examples, so that you can learn how to write more advanced 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 foobar

This 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 foobar

or to use the same completions for several commands:

> compdef _function foobar goocar hoodar

or if you want to supply arguments:

> compdef '_function arg1 arg2' foobar

See 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 foobar

or to use _gnu_generic with several different commands:

> compdef _gnu_generic foobar goocar hoodar

This 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=cmd2

This 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 _regex_arguments which are easier to use.

Utility functions

Here is a list of some of the utility functions that may be of use. The full list of utility functions, with full explanations, is available here.

main utility functions for overall completion

_arguments	Used to specify how to complete individual command line options for a command with unix style options. Often used.
_regex_arguments	Creates a function for matching commandline arguments with regular expressions, and then performing actions/completions.
_gnu_generic	Can be used to complete options for commands that understand the `–help' option.
_alternative	Loop over tag labels and perform actions based on matching tag label.

functions for performing complex completions

_values	Used for completing arbitrary keywords (values) and their arguments, or comma separated lists of such combinations.
_combination	Used to complete combinations of values, for example pairs of hostnames and usernames.
_multi_parts	Used for completing multiple parts of words separately where each part is separated by some char, e.g. for completing partial filepaths: /u/i/sy -> /usr/include/sys
_sep_parts	Like _multi_parts but allows different separators at different parts of the completion.

functions for completing specific types of objects

_path_files	Used to complete filepaths. Take several options to control behaviour.
_files	Calls _path_files with all options except -g and -/. These options depend on file-patterns style setting.
_net_interfaces	Used for completing network interface names
_users	Used for completing user names
_groups	Used for completing group names
_options	Used for completing the names of shell options.
_parameters	Used for completing the names of shell parameters/variables (can restrict to those matching a pattern).

other functions

_message	Used for displaying help messages in places where no completions can be generated.
_regex_words	Can be used to generate arguments for the _regex_arguments command. This is easier than writing the arguments manually.
_guard	Can be used in the ACTION of specifications for _arguments and similar functions to check the word being completed.

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.

There are a couple of tutorials on how to use _arguments here and here, so I won't cover any more here. Also have a look at the many completion functions listed here many of which use _arguments. The full documentation for _arguments is available here.

Actions

Many of the utility functions such as _arguments, _regex_arguments, _alternative and _values may include an action at the end of an option/argument specification. This action indicates how to complete the corresponding argument. The actions can take one of the following forms:

( )	Argument is required but no matches are generated for it.
(ITEM1 ITEM2 ETC)	List of possible matches
((ITEM1\:DESC1 ITEM2\:DESC2 ETC\:BLAH))	List of possible matches, with descriptions.
->STRING	Set $state to STRING and continue ($state can be checked in a case statement after the utility function call)
{EVAL-STRING}	Evaluate string as shell code to generate matches.
\=ACTION	Inserts a dummy word into completion command line without changing the point at which completion takes place.

Not all action types are available for all utility functions that use them. For example the ->STRING type is not available in the _regex_arguments or _alternative functions.

Examples

Here the non-option argument

_arguments '--help[show help]' '-?[show help]' '1:First arg:_files'

Patterns

Writing completion functions using _values

The _values function

Functions for completing specific types of objects

_files	completes files & directories
_net_interfaces	completes network interface names
_values	for completing comma se

Utility functions with example code

compadd

_gnu_generic

_arguments

_regex_arguments

_regex_words

_values

_comma_separated

_files

_net_interfaces

testing & debugging

To reload a completion function:

> unfunction _func
> autoload -U _func

gotchas

Putting it all together

Other resources

Here is a nicely formatted short tutorial showing basic usage of the _arguments function, and here is a slightly more advanced tutorial using the _arguments function. Here is the zshcompsys man page.