If the system was installed completely, it should be enough to
call the shell function compinit
from your initialization file; see the
next section. However, the function compinstall
can be run by a user
to configure various aspects of the completion system.
Usually, compinstall
will insert code into .zshrc
, although if
that is not writable it will save it in another file and tell you that
file’s location. Note that it is up to you to make sure that the lines
added to .zshrc
are actually run; you may, for example, need to move
them to an earlier place in the file if .zshrc
usually returns early.
So long as you keep them all together (including the comment lines at the
start and finish), you can rerun compinstall
and it will correctly
locate and modify these lines. Note, however, that any code you add to
this section by hand is likely to be lost if you rerun compinstall
,
although lines using the command ‘zstyle
’ should be gracefully handled.
The new code will take effect next time you start the shell, or run
.zshrc
by hand; there is also an option to make them take effect
immediately. However, if compinstall
has removed definitions, you will
need to restart the shell to see the changes.
To run compinstall
you will need to make sure it is in a directory
mentioned in your fpath
parameter, which should already be the case if
zsh was properly configured as long as your startup files do not remove the
appropriate directories from fpath
. Then it must be autoloaded
(‘autoload -U compinstall
’ is recommended). You can abort the
installation any time you are being prompted for information, and your
.zshrc
will not be altered at all; changes only take place right at the
end, where you are specifically asked for confirmation.
This section describes the use of compinit
to initialize completion for
the current session when called directly; if you have run
compinstall
it will be called automatically from your .zshrc
.
To initialize the system, the function compinit
should be in a
directory mentioned in the fpath
parameter, and should be autoloaded
(‘autoload -U compinit
’ is recommended), and then run simply as
‘compinit
’. This will define a
few utility functions, arrange for all the necessary shell functions to be
autoloaded, and will then re-define all widgets that do completion to use the
new system. If you use the menu-select
widget, which is part of the
zsh/complist
module, you should make sure that that module is loaded
before the call to compinit
so that that widget is also
re-defined. If completion styles (see below) are set up to perform
expansion as well as completion by default, and the TAB key is bound to
expand-or-complete
, compinit
will rebind it to complete-word
;
this is necessary to use the correct form of expansion.
Should you need to use the original completion commands, you can still
bind keys to the old widgets by putting a ‘.
’ in front of the
widget name, e.g. ‘.expand-or-complete
’.
To speed up the running of compinit
, it can be made to produce a dumped
configuration that will be read in on future invocations; this is the
default, but can be turned off by calling compinit
with the
option -D
. The dumped file is .zcompdump
in the same
directory as the startup files (i.e. $ZDOTDIR
or $HOME
);
alternatively, an explicit file name can be given by ‘compinit -d
dumpfile’. The next invocation of compinit
will read the dumped
file instead of performing a full initialization.
If the number of completion files changes, compinit
will recognise this
and produce a new dump file. However, if the name of a function or the
arguments in the first line of a #compdef
function (as described below)
change, it is easiest to delete the dump file by hand so that
compinit
will re-create it the next time it is run. The check
performed to see if there are new functions can be omitted by giving
the option -C
. In this case the dump file will only be created if
there isn’t one already.
The dumping is actually done by another function, compdump
, but you
will only need to run this yourself if you change the configuration
(e.g. using compdef
) and then want to dump the new one. The name of
the old dumped file will be remembered for this purpose.
If the parameter _compdir
is set, compinit
uses it as a directory
where completion functions can be found; this is only necessary if they are
not already in the function search path.
For security reasons compinit
also checks if the completion system
would use files not owned by root or by the current user, or files in
directories that are world- or group-writable or that are not owned by
root or by the current user. If such files or directories are found,
compinit
will ask if the completion system should really be used. To
avoid these tests and make all files found be used without asking, use the
option -u
, and to make compinit
silently ignore all insecure files
and directories use the option -i
. This security check is skipped
entirely when the -C
option is given, provided the dumpfile exists.
The security check can be retried at any time by running the function
compaudit
. This is the same check used by compinit
, but when it
is executed directly any changes to fpath
are made local to the
function so they do not persist. The directories to be checked may be
passed as arguments; if none are given, compaudit
uses fpath
and
_compdir
to find completion system directories, adding missing ones
to fpath
as necessary. To force a check of exactly the directories
currently named in fpath
, set _compdir
to an empty string before
calling compaudit
or compinit
.
The function bashcompinit
provides compatibility with bash’s programmable
completion system. When run it will define the functions, compgen
and
complete
which correspond to the bash builtins with the same names.
It will then be possible to use completion specifications and functions
written for bash.
The convention for autoloaded functions used in completion is that they
start with an underscore; as already mentioned, the fpath/FPATH
parameter must contain the directory in which they are stored. If zsh
was properly installed on your system, then fpath/FPATH
automatically
contains the required directories for the standard functions.
For incomplete installations, if compinit
does not find enough files
beginning with an underscore (fewer than twenty) in the search path, it
will try to find more by adding the directory _compdir
to the search
path. If that directory has a subdirectory named Base
, all
subdirectories will be added to the path. Furthermore, if the subdirectory
Base
has a subdirectory named Core
, compinit
will add all
subdirectories of the subdirectories to the path: this allows
the functions to be in the same format as in the zsh
source
distribution.
When compinit
is run, it searches all such files accessible via
fpath/FPATH
and reads the first line of each of them. This line should
contain one of the tags described below. Files whose first line does not
start with one of these tags are not considered to be part of the
completion system and will not be treated specially.
The tags are:
#compdef
name ... [ -
{p
|P
} pattern ... [ -N
name ... ] ]The file will be made autoloadable and the function defined
in it will be called when completing names, each of which is
either the name of a command whose arguments are to be completed or one of
a number of special contexts in the form -
context-
described
below.
Each name may also be of the form ‘cmd=
service’.
When completing the command cmd, the function typically behaves as
if the command (or special context) service was being completed
instead. This provides a way of altering the behaviour of functions
that can perform many different completions. It is implemented
by setting the parameter $service
when calling the function;
the function may choose to interpret this how it wishes, and simpler
functions will probably ignore it.
If the #compdef
line contains one of the options -p
or -P
,
the words following are taken to be patterns. The function will be
called when completion is attempted for a command or context that matches
one of the patterns. The options -p
and -P
are used to specify
patterns to be tried before or after other completions respectively.
Hence -P
may be used to specify default actions.
The option -N
is used after a list following -p
or -P
; it
specifies that remaining words no longer define patterns. It is
possible to toggle between the three options as many times as necessary.
#compdef -k
style key-sequence ...This option creates a widget behaving like the
builtin widget style and binds it to the given key-sequences,
if any. The style must be one of the builtin widgets that perform
completion, namely complete-word
, delete-char-or-list
,
expand-or-complete
, expand-or-complete-prefix
, list-choices
,
menu-complete
, menu-expand-or-complete
, or
reverse-menu-complete
. If the zsh/complist
module is loaded (see
The zsh/complist Module) the widget menu-select
is also available.
When one of the key-sequences is typed, the function in the file will
be invoked to generate the matches. Note that a key will not be re-bound
if it already was (that is, was bound to something other than
undefined-key
). The widget created has the same name as the file and
can be bound to any other keys using bindkey
as usual.
#compdef -K
widget-name style key-sequence [ name style seq ... ]This is similar to -k
except that only one key-sequence
argument may be given for each widget-name style pair.
However, the entire set of three arguments may be repeated with a
different set of arguments. Note in particular that the
widget-name must be distinct in each set. If it does not begin with
‘_
’ this will be added. The widget-name should not clash with
the name of any existing widget: names based on the name of the function
are most useful. For example,
#compdef -K _foo_complete complete-word "^X^C" \ _foo_list list-choices "^X^D"
(all on one line) defines a widget _foo_complete
for completion, bound
to ‘^X^C
’, and a widget _foo_list
for listing, bound to ‘^X^D
’.
#autoload
[ options ]Functions with the #autoload
tag are marked for autoloading but
are not otherwise treated specially. Typically they are to be called
from within one of the completion functions. Any options supplied
will be passed to the autoload
builtin; a typical use is +X
to
force the function to be loaded immediately. Note that the -U
and
-z
flags are always added implicitly.
The #
is part of the tag name and no white space is allowed after it.
The #compdef
tags use the compdef
function described below; the
main difference is that the name of the function is supplied implicitly.
The special contexts for which completion functions can be defined are:
-array-value-
The right hand side of an array-assignment
(‘name=(
...)
’)
-assign-parameter-
The name of a parameter in an assignment, i.e. on the left hand side of
an ‘=
’
-brace-parameter-
The name of a parameter expansion within braces (‘${
...}
’)
-command-
A word in command position
-condition-
A word inside a condition (‘[[
...]]
’)
-default-
Any word for which no other completion is defined
-equal-
A word beginning with an equals sign
-first-
This is tried before any other completion function. The function called
may set the _compskip
parameter to one of various values:
all
: no further completion is attempted; a string
containing the substring patterns
: no pattern completion functions
will be called; a string containing default
: the
function for the ‘-default-
’ context will not be called, but
functions defined for commands will be.
-math-
Inside mathematical contexts, such as
‘((
...))
’
-parameter-
The name of a parameter expansion (‘$
...’)
-redirect-
The word after a redirection operator.
-subscript-
The contents of a parameter subscript.
-tilde-
After an initial tilde (‘~
’), but before the first slash
in the word.
-value-
On the right hand side of an assignment.
Default implementations are supplied for each of these
contexts. In most cases the context -
context-
is
implemented by a corresponding function _
context, for example
the context ‘-tilde-
’ and the function ‘_tilde
’).
The contexts -redirect-
and -value-
allow extra context-specific
information. (Internally, this is handled by the functions for each
context calling the function _dispatch
.) The extra
information is added separated by commas.
For the -redirect-
context, the extra information is in the form
‘-redirect-,
op,
command’, where op is the
redirection operator and command is the name of the command on
the line. If there is no command on the line yet, the command
field will be empty.
For the -value-
context, the form is
‘-value-,
name,
command’, where name is the name of
the parameter on the left hand side of the assignment.
In the case of elements of an associative array, for
example ‘assoc=(key <TAB>
’, name is expanded to
‘name-
key’. In certain special contexts, such as
completing after ‘make CFLAGS=
’, the command part gives the
name of the command, here make
; otherwise it is empty.
It is not necessary to define fully specific completions as the
functions provided will try to generate completions by progressively
replacing the elements with ‘-default-
’. For example, when
completing after ‘foo=<TAB>
’, _value
will try the names
‘-value-,foo,
’ (note the empty command part),
‘-value-,foo,-default-
’ and‘-value-,-default-,-default-
’, in
that order, until it finds a function to handle the context.
As an example:
compdef '_files -g "*.log"' '-redirect-,2>,-default-'
completes files matching ‘*.log
’ after ‘2> <TAB>
’ for any
command with no more specific handler defined.
Also:
compdef _foo -value-,-default-,-default-
specifies that _foo
provides completions for the values of
parameters for which no special function has been defined. This is
usually handled by the function _value
itself.
The same lookup rules are used when looking up styles (as described below); for example
zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'
is another way to make completion after ‘2> <TAB>
’ complete files
matching ‘*.log
’.
The following function is defined by compinit
and may be called
directly.
compdef
[ -ane
] function name ... [ -
{p
|P
} pattern ... [ -N
name ...]]compdef -d
name ...compdef -k
[ -an
] function style key-sequence [ key-sequence ... ]compdef -K
[ -an
] function name style key-seq [ name style seq ... ]The first form defines the function to call for completion in the
given contexts as described for the #compdef
tag above.
Alternatively, all the arguments may have the form
‘cmd=
service’. Here service should already have been
defined by ‘cmd1=
service’ lines in #compdef
files, as
described above. The argument for cmd will be completed in the
same way as service.
The function argument may alternatively be a string containing
almost any shell code. If the string contains an equal sign, the above
will take precedence. The option -e
may be used to specify the first
argument is to be evaluated as shell code even if it contains an equal
sign. The string will be executed using the eval
builtin command to
generate completions. This provides a way of avoiding having to define
a new completion function. For example, to complete files ending in
‘.h
’ as arguments to the command foo
:
compdef '_files -g "*.h"' foo
The option -n
prevents any completions already defined for the
command or context from being overwritten.
The option -d
deletes any completion defined for the command or
contexts listed.
The names may also contain -p
, -P
and -N
options as
described for the #compdef
tag. The effect on the argument list is
identical, switching between definitions of patterns tried initially,
patterns tried finally, and normal commands and contexts.
The parameter $_compskip
may be set by any function defined for a
pattern context. If it is set to a value containing the substring
‘patterns
’ none of the pattern-functions will be called; if it is
set to a value containing the substring ‘all
’, no other function
will be called. Setting $_compskip
in this manner is of particular
utility when using the -p
option, as otherwise the dispatcher will
move on to additional functions (likely the default one) after calling
the pattern-context one, which can mangle the display of completion
possibilities if not handled properly.
The form with -k
defines a widget with the same name as the function
that will be called for each of the key-sequences; this is like the
#compdef -k
tag. The function should generate the completions needed
and will otherwise behave like the builtin widget whose name is given as
the style argument. The widgets usable for this are:
complete-word
, delete-char-or-list
, expand-or-complete
,
expand-or-complete-prefix
, list-choices
, menu-complete
,
menu-expand-or-complete
, and reverse-menu-complete
, as well as
menu-select
if the zsh/complist
module is loaded. The option -n
prevents the key being bound if it is already to bound to something other
than undefined-key
.
The form with -K
is similar and defines multiple widgets based on the
same function, each of which requires the set of three arguments
name, style and key-sequence, where the latter two are as
for -k
and the first must be a unique widget name beginning with an
underscore.
Wherever applicable, the -a
option makes the function
autoloadable, equivalent to autoload -U
function.
The function compdef
can be used to associate existing completion
functions with new commands. For example,
compdef _pids foo
uses the function _pids
to complete process IDs for the command foo
.
Note also the _gnu_generic
function described below, which can be
used to complete options for commands that understand the
‘-
-help
’ option.