This section gives a short overview of how the completion system works, and then more detail on how users can configure how and when matches are generated.
When completion is attempted somewhere on the command line the
completion system begins building the context. The context represents
everything that the shell knows about the meaning of the command line
and the significance of the cursor position. This takes account of a
number of things including the command word (such as ‘grep
’ or
‘zsh
’) and options to which the current word may be an argument
(such as the ‘-o
’ option to zsh
which takes a shell option as an
argument).
The context starts out very generic ("we are beginning a completion") and becomes more specific as more is learned ("the current word is in a position that is usually a command name" or "the current word might be a variable name" and so on). Therefore the context will vary during the same call to the completion system.
This context information is condensed into a string consisting of multiple fields separated by colons, referred to simply as ‘the context’ in the remainder of the documentation. Note that a user of the completion system rarely needs to compose a context string, unless for example a new function is being written to perform completion for a new command. What a user may need to do is compose a style pattern, which is matched against a context when needed to look up context-sensitive options that configure the completion system.
The next few paragraphs explain how a context is composed within the
completion function suite. Following that is discussion of how styles
are defined. Styles determine such things as how the matches are
generated, similarly to shell options but with much more control. They
are defined with the zstyle
builtin command (The zsh/zutil Module).
The context string always consists of a fixed set of fields, separated
by colons and with a leading colon before the first. Fields which are
not yet known are left empty, but the surrounding colons appear anyway.
The fields are always in the order
:completion:
function:
completer:
command:
argument:
tag. These have the following meaning:
completion
, saying that this style is used by
the completion system. This distinguishes the context from those used
by, for example, zle widgets and ZFTP functions.
predict-on
and the various
functions in the Widget
directory of the distribution to the name of
that function, often in an abbreviated form.
complete
’ is the simplest, but other completers exist to perform
related tasks such as correction, or to modify the behaviour of a later
completer. See
Control Functions
for more information.
-
context-
, just at it appears
following the #compdef
tag or the compdef
function. Completion
functions for commands that have sub-commands usually modify this field
to contain the name of the command followed by a minus sign and the
sub-command. For example, the completion function for the cvs
command sets this field to cvs-add
when completing arguments to
the add
subcommand.
argument-
n, where n is the number of the argument,
and for arguments to options the form option-
opt-
n
where n is the number of the argument to option opt. However,
this is only the case if the command line is parsed with standard
UNIX-style options and arguments, so many completions do not set this.
The context is gradually put together as the functions are executed, starting
with the main entry point, which adds :completion:
and the function
element if necessary. The completer then adds the completer element.
The contextual completion adds the command and argument options.
Finally, the tag is added when the types of completion are known.
For example, the context name
:completion::complete:dvips:option-o-1:files
says that normal completion was attempted as the first argument to the
option -o
of the command dvips
:
dvips -o ...
and the completion function will generate filenames.
Usually completion will be tried for all possible tags in an order given
by the completion function. However, this can be altered by using the
tag-order
style. Completion is then restricted to the list of given
tags in the given order.
The _complete_help
bindable command shows all the contexts and tags
available for completion at a particular point. This provides an easy
way of finding information for tag-order
and other styles. It is
described in
Bindable Commands.
When looking up styles the completion system uses full context names, including the tag. Looking up the value of a style therefore consists of two things: the context, which is matched to the most specific (best fitting) pattern, and the name of the style itself, which must be matched exactly. The following examples demonstrate that patterns may be loosely defined for styles that apply broadly, or as tightly defined as desired for styles that apply in narrower circumstances.
For example, many completion functions can generate matches in a
simple and a verbose form and use the verbose
style to decide
which form should be used. To make all such functions use the verbose form,
put
zstyle ':completion:*' verbose yes
in a startup file (probably .zshrc
).
This gives the verbose
style the value yes
in every
context inside the completion system, unless that context has a more
specific definition. It is best to avoid giving the pattern as ‘*
’
in case the style has some meaning outside the completion system.
Many such general purpose styles can be configured simply by using the
compinstall
function.
A more specific example of the use of the verbose
style is by the
completion for the kill
builtin. If the style is set, the builtin
lists full job texts and process command lines; otherwise it shows the
bare job numbers and PIDs. To turn the style off for this use only:
zstyle ':completion:*:*:kill:*:*' verbose no
For even more control, the style can use one of the tags ‘jobs
’ or
‘processes
’. To turn off verbose display only for jobs:
zstyle ':completion:*:*:kill:*:jobs' verbose no
The -e
option to zstyle
even allows completion function code to
appear as the argument to a style; this requires some understanding of
the internals of completion functions (see
Completion Widgets)). For example,
zstyle -e ':completion:*' hosts 'reply=($myhosts)'
This forces the value of the hosts
style to be read from the
variable myhosts
each time a host name is needed; this is useful
if the value of myhosts
can change dynamically.
For another useful example, see the example in the description of the
file-list
style below. This form can be
slow and should be avoided for commonly examined styles such
as menu
and list-rows-first
.
Note that the order in which styles are defined does not matter; the
style mechanism uses the most specific possible match for a particular
style to determine the set of values. Strings are
preferred over patterns (for example, ‘:completion::complete:::foo
’ is
more specific than ‘:completion::complete:::*'
), and longer patterns are
preferred over the pattern ‘*
’. See
The zsh/zutil Module
for details.
Context patterns that use something other than a wildcard (*
) to match the
middle parts of the context — the completer, command, and
argument in
:completion:
function:
completer:
command:
argument:
tag
— should include all six colons (:
) explicitly. Without this,
a pattern such as :completion:*:foo:*
could match foo
against a
component other than the intended one (for example, against completer when
a match against command was intended).
Style names like those of tags are arbitrary and depend on the completion function. However, the following two sections list some of the most common tags and styles.
Some of the following are only used when looking up particular styles and do not refer to a type of match.
accounts
used to look up the users-hosts
style
all-expansions
used by the _expand
completer when adding the single string containing
all possible expansions
all-files
for the names of all files (as distinct from a particular subset, see the
globbed-files
tag).
arguments
for arguments to a command
arrays
for names of array parameters
association-keys
for keys of associative arrays; used when completing inside a subscript to a parameter of this type
bookmarks
when completing bookmarks (e.g. for URLs and the zftp
function suite)
builtins
for names of builtin commands
characters
for single characters in arguments of commands such as stty
. Also used
when completing character classes after an opening bracket
colormapids
for X colormap ids
colors
for color names
commands
for names of external commands. Also used by complex commands such as
cvs
when completing names subcommands.
contexts
for contexts in arguments to the zstyle
builtin command
corrections
used by the _approximate
and _correct
completers for possible
corrections
cursors
for cursor names used by X programs
default
used in some contexts to provide a way of supplying a default when more specific tags are also valid. Note that this tag is used when only the function field of the context name is set
descriptions
used when looking up the value of the format
style to generate
descriptions for types of matches
devices
for names of device special files
directories
for names of directories — local-directories
is used instead
when completing arguments of cd
and related builtin commands when
the cdpath
array is set
directory-stack
for entries in the directory stack
displays
for X display names
domains
for network domains
email-
pluginfor email addresses from the ‘_email-
plugin’ backend of _email_addresses
expansions
used by the _expand
completer for individual words (as opposed to
the complete set of expansions) resulting from the expansion of a word
on the command line
extensions
for X server extensions
file-descriptors
for numbers of open file descriptors
files
the generic file-matching tag used by functions completing filenames
fonts
for X font names
fstypes
for file system types (e.g. for the mount
command)
functions
names of functions — normally shell functions, although certain commands may understand other kinds of function
globbed-files
for filenames when the name has been generated by pattern matching
groups
for names of user groups
history-words
for words from the history
hosts
for hostnames
indexes
for array indexes
interfaces
for network interfaces
jobs
for jobs (as listed by the ‘jobs
’ builtin)
keymaps
for names of zsh keymaps
keysyms
for names of X keysyms
libraries
for names of system libraries
limits
for system limits
local-directories
for names of directories that are subdirectories of the current working
directory when completing arguments of cd
and related builtin
commands (compare path-directories
) — when the cdpath
array is unset, directories
is used instead
mailboxes
for e-mail folders
manuals
for names of manual pages
maps
for map names (e.g. NIS maps)
messages
used to look up the format
style for messages
modifiers
for names of X modifiers
modules
for modules (e.g. zsh
modules)
my-accounts
used to look up the users-hosts
style
named-directories
for named directories (you wouldn’t have guessed that, would you?)
names
for all kinds of names
newsgroups
for USENET groups
nicknames
for nicknames of NIS maps
options
for command options
original
used by the _approximate
, _correct
and _expand
completers when
offering the original string as a match
other-accounts
used to look up the users-hosts
style
packages
for packages (e.g. rpm
or installed Debian
packages)
parameters
for names of parameters
path-directories
for names of directories found by searching the cdpath
array when
completing arguments of cd
and related builtin commands (compare
local-directories
)
paths
used to look up the values of the expand
, ambiguous
and
special-dirs
styles
pods
for perl pods (documentation files)
ports
for communication ports
prefixes
for prefixes (like those of a URL)
printers
for print queue names
processes
for process identifiers
processes-names
used to look up the command
style when generating the names of
processes for killall
sequences
for sequences (e.g. mh
sequences)
sessions
for sessions in the zftp
function suite
signals
for signal names
strings
for strings (e.g. the replacement strings for the cd
builtin
command)
styles
for styles used by the zstyle builtin command
suffixes
for filename extensions
tags
for tags (e.g. rpm
tags)
targets
for makefile targets
time-zones
for time zones (e.g. when setting the TZ
parameter)
types
for types of whatever (e.g. address types for the xhost
command)
urls
used to look up the urls
and local
styles when completing URLs
users
for usernames
values
for one of a set of values in certain lists
variant
used by _pick_variant
to look up the command to run when determining
what program is installed for a particular command name.
visuals
for X visuals
warnings
used to look up the format
style for warnings
widgets
for zsh widget names
windows
for IDs of X windows
zsh-options
for shell options
Note that the values of several of these styles represent boolean
values. Any of the strings ‘true
’, ‘on
’,
‘yes
’, and ‘1
’ can be used for the value ‘true’ and
any of the strings ‘false
’, ‘off
’, ‘no
’, and ‘0
’ for
the value ‘false’. The behavior for any other value is undefined
except where explicitly mentioned. The default value may
be either ‘true’ or ‘false’ if the style is not set.
Some of these styles are tested first for every possible tag
corresponding to a type of match, and if no style was found, for the
default
tag. The most notable styles of this type are menu
,
list-colors
and styles controlling completion listing such as
list-packed
and last-prompt
. When tested for the default
tag, only the function field of the context will be set so that
a style using the default
tag will normally be defined along the lines of:
zstyle ':completion:*:default' menu ...
accept-exact
This is tested for the default
tag in addition to the tags valid for
the current context. If it is set to ‘true’ and any of the trial
matches is the same as the string on the command line, this match will
immediately be accepted (even if it would otherwise be considered
ambiguous).
When completing pathnames (where the tag used is ‘paths
’)
this style accepts any number of patterns as the value in addition to
the boolean values. Pathnames matching one of these
patterns will be accepted immediately even if the command line contains
some more partially typed pathname components and these match no file
under the directory accepted.
This style is also used by the _expand
completer to decide if
words beginning with a tilde or parameter expansion should be
expanded. For example, if there are parameters
foo
and foobar
, the string ‘$foo
’ will only be expanded if
accept-exact
is set to ‘true’; otherwise the completion system will
be allowed to complete $foo
to $foobar
. If the style is set to
‘continue
’, _expand
will add the expansion as a match and the completion
system will also be allowed to continue.
accept-exact-dirs
This is used by filename completion. Unlike accept-exact
it is
a boolean. By default, filename completion examines all components
of a path to see if there are completions of that component, even if
the component matches an existing directory. For example, when
completion after /usr/bin/
, the function examines possible
completions to /usr
.
When this style is ‘true’, any prefix of a path that matches an existing
directory is accepted without any attempt to complete it further.
Hence, in the given example, the path /usr/bin/
is accepted
immediately and completion tried in that directory.
This style is also useful when completing after directories that
magically appear when referenced, such as ZFS .zfs
directories
or NetApp .snapshot
directories. When the style is set the
shell does not check for the existence of the directory within the
parent directory.
If you wish to inhibit this behaviour entirely, set the path-completion
style (see below) to ‘false’.
add-space
This style is used by the _expand
completer. If it is ‘true’ (the
default), a space will be inserted after all words resulting from the
expansion, or a slash in the case of directory names. If the value
is ‘file
’, the completer will only add a space
to names of existing files. Either a boolean ‘true’ or the value
‘file
’ may be combined with ‘subst
’, in which case the completer
will not add a space to words generated from the expansion of a
substitution of the form ‘$(
...)
’ or ‘${
...}
’.
The _prefix
completer uses this style as a simple boolean value
to decide if a space should be inserted before the suffix.
ambiguous
This applies when completing non-final components of filename paths, in
other words those with a trailing slash. If it is set, the cursor is
left after the first ambiguous component, even if menu completion is in
use. The style is always tested with the paths
tag.
assign-list
When completing after an equals sign that is being treated as an
assignment, the completion system normally completes only one filename.
In some cases the value may be a list of filenames separated by colons,
as with PATH
and similar parameters. This style can be set to a
list of patterns matching the names of such parameters.
The default is to complete lists when the word on the line already contains a colon.
auto-description
If set, this style’s value will be used as the description for options that
are not described by the completion functions, but that have exactly
one argument. The sequence ‘%d
’ in the value will be replaced by
the description for this argument. Depending on personal preferences,
it may be useful to set this style to something like ‘specify: %d
’.
Note that this may not work for some commands.
avoid-completer
This is used by the _all_matches
completer to decide if the string
consisting of all matches should be added to the list currently being
generated. Its value is a list of names of completers. If any of
these is the name of the completer that generated the matches in this
completion, the string will not be added.
The default value for this style is ‘_expand _old_list _correct
_approximate
’, i.e. it contains the completers for which a string
with all matches will almost never be wanted.
cache-path
This style defines the path where any cache files containing dumped
completion data are stored. It defaults to ‘$ZDOTDIR/.zcompcache
’, or
‘$HOME/.zcompcache
’ if $ZDOTDIR
is not defined. The completion
cache will not be used unless the use-cache
style is set.
cache-policy
This style defines the function that will be used to determine whether
a cache needs rebuilding. See the section on the _cache_invalid
function below.
call-command
This style is used in the function for commands such as make
and
ant
where calling the command directly to generate matches suffers
problems such as being slow or, as in the case of make
can
potentially cause actions in the makefile to be executed. If it is set
to ‘true’ the command is called to generate matches. The default value
of this style is ‘false’.
command
In many places, completion functions need to call external commands to
generate the list of completions. This style can be used to override the
command that is called in some such cases. The elements of the value are
joined with spaces to form a command line to execute. The value can also
start with a hyphen, in which case the usual command will be added to the
end; this is most useful for putting ‘builtin
’ or ‘command
’ in
front to make sure the appropriate version of a command is called, for
example to avoid calling a shell function with the same name as an external
command.
As an example, the completion function for process IDs uses this
style with the processes
tag to generate the IDs to complete and
the list of processes to display (if the verbose
style is ‘true’).
The list produced by the command should look like the output of the
ps
command. The first line is not displayed, but is searched for
the string ‘PID
’ (or ‘pid
’) to find the position of the
process IDs in the following lines. If the line does not contain
‘PID
’, the first numbers in each of the other lines are taken as the
process IDs to complete.
Note that the completion function generally has to call the specified command for each attempt to generate the completion list. Hence care should be taken to specify only commands that take a short time to run, and in particular to avoid any that may never terminate.
command-path
This is a list of directories to search for commands to complete. The
default for this style is the value of the special parameter path
.
commands
This is used by the function completing sub-commands for the system
initialisation scripts (residing in /etc/init.d
or somewhere not
too far away from that). Its values give the default commands to
complete for those commands for which the completion function isn’t
able to find them out automatically. The default for this style are
the two strings ‘start
’ and ‘stop
’.
complete
This is used by the _expand_alias
function when invoked as a
bindable command. If set to ‘true’ and the word on the command
line is not the name of an alias, matching alias names will be
completed.
complete-options
This is used by the completer for cd
, chdir
and pushd
.
For these commands a -
is used to introduce a directory stack entry
and completion of these is far more common than completing options.
Hence unless the value of this style is ‘true’ options will not be
completed, even after an initial -
. If it is ‘true’, options will
be completed after an initial -
unless there is a preceding
-
-
on the command line.
completer
The strings given as the value of this style provide the names of the completer functions to use. The available completer functions are described in Control Functions.
Each string may be either the name of a completer function or a string
of the form ‘function:
name’. In the first case the
completer field of the context will contain the name of the
completer without the leading underscore and with all other
underscores replaced by hyphens. In the second case the
function is the name of the completer to call, but the context
will contain the user-defined name in the completer field of
the context. If the name starts with a hyphen, the string for the
context will be build from the name of the completer function as in
the first case with the name appended to it. For example:
zstyle ':completion:*' completer _complete _complete:-foo
Here, completion will call the _complete
completer twice, once
using ‘complete
’ and once using ‘complete-foo
’ in the
completer field of the context. Normally, using the same
completer more than once only makes sense when used with the
‘functions:
name’ form, because otherwise the context
name will be the same in all calls to the completer; possible
exceptions to this rule are the _ignored
and _prefix
completers.
The default value for this style is ‘_complete _ignored
’:
only completion will be done, first using the ignored-patterns
style
and the $fignore
array and then without ignoring matches.
condition
This style is used by the _list
completer function to decide if
insertion of matches should be delayed unconditionally. The default is
‘true’.
delimiters
This style is used when adding a delimiter for use with history
modifiers or glob qualifiers that have delimited arguments. It is
an array of preferred delimiters to add. Non-special characters are
preferred as the completion system may otherwise become confused.
The default list is :
, +
, /
, -
, %
. The list
may be empty to force a delimiter to be typed.
disabled
If this is set to ‘true’, the _expand_alias
completer and bindable
command will try to expand disabled aliases, too. The default is
‘false’.
domains
A list of names of network domains for completion.
If this is not set, domain names will be taken from
the file /etc/resolv.conf
.
environ
The environ style is used when completing for ‘sudo
’. It is set to an
array of ‘VAR=
value’ assignments to be exported into the
local environment before the completion for the target command is invoked.
zstyle ':completion:*:sudo::' environ \ PATH="/sbin:/usr/sbin:$PATH" HOME="/root"
expand
This style is used when completing strings consisting of multiple parts, such as path names.
If one of its values is the string ‘prefix
’, the partially typed
word from the line will be expanded as far as possible even if trailing
parts cannot be completed.
If one of its values is the string ‘suffix
’, matching names for
components after the first ambiguous one will also be added. This means
that the resulting string is the longest unambiguous string possible.
However, menu completion can be used to cycle through all matches.
extra-verbose
If set, the completion listing is more verbose at the cost of a probable decrease in completion speed. Completion performance will suffer if this style is set to ‘true’.
fake
This style may be set for any completion context. It
specifies additional strings that will always be completed in that
context. The form of each string is ‘value:
description’;
the colon and description may be omitted, but any literal colons in
value must be quoted with a backslash. Any description
provided is shown alongside the value in completion listings.
It is important to use a sufficiently restrictive context when specifying
fake strings. Note that the styles fake-files
and fake-parameters
provide additional features when completing files or parameters.
fake-always
This works identically to the fake
style except that
the ignored-patterns
style is not applied to it. This makes it
possible to override a set of matches completely by setting the
ignored patterns to ‘*
’.
The following shows a way of supplementing any tag with arbitrary data, but
having it behave for display purposes like a separate tag. In this example
we use the features of the tag-order
style to divide the
named-directories
tag into two when performing completion with
the standard completer complete
for arguments of cd
. The tag
named-directories-normal
behaves as normal, but the tag
named-directories-mine
contains a fixed set of directories.
This has the effect of adding the match group ‘extra directories
’ with
the given completions.
zstyle ':completion::complete:cd:*' tag-order \ 'named-directories:-mine:extra\ directories named-directories:-normal:named\ directories *' zstyle ':completion::complete:cd:*:named-directories-mine' \ fake-always mydir1 mydir2 zstyle ':completion::complete:cd:*:named-directories-mine' \ ignored-patterns '*'
fake-files
This style is used when completing files and looked up
without a tag. Its values are of the form
‘dir:
names...’. This will add the names (strings
separated by spaces) as
possible matches when completing in the directory dir, even if no
such files really exist. The dir may be a pattern; pattern characters
or colons in dir should be quoted with a backslash to be treated
literally.
This can be useful on systems that support special file systems whose
top-level pathnames can not be listed or generated with glob patterns
(but see accept-exact-dirs
for a more general way of dealing
with this problem). It can also be used for directories for which one
does not have read permission.
The pattern form can be used to add a certain ‘magic’ entry to all directories on a particular file system.
fake-parameters
This is used by the completion function for parameter names.
Its values are names of parameters that might not yet be
set but should be completed nonetheless. Each name may also be
followed by a colon and a string specifying the type of the parameter
(like ‘scalar
’, ‘array
’ or ‘integer
’). If the type is
given, the name will only be completed if parameters of that type are
required in the particular context. Names for which no type is
specified will always be completed.
file-list
This style controls whether files completed using the standard builtin
mechanism are to be listed with a long list similar to ls -l
.
Note that this feature uses the shell module
zsh/stat
for file information; this loads the builtin stat
which will replace any external stat
executable. To avoid
this the following code can be included in an initialization file:
zmodload -i zsh/stat disable stat
The style may either be set to a ‘true’ value (or ‘all
’), or
one of the values ‘insert
’ or ‘list
’, indicating that files
are to be listed in long format in all circumstances, or when
attempting to insert a file name, or when listing file names
without attempting to insert one.
More generally, the value may be an array of any of the above values,
optionally followed by =
num. If num is present it
gives the maximum number of matches for which long listing style
will be used. For example,
zstyle ':completion:*' file-list list=20 insert=10
specifies that long format will be used when listing up to 20 files or inserting a file with up to 10 matches (assuming a listing is to be shown at all, for example on an ambiguous completion), else short format will be used.
zstyle -e ':completion:*' file-list \ '(( ${+NUMERIC} )) && reply=(true)'
specifies that long format will be used any time a numeric argument is supplied, else short format.
file-patterns
This is used by the standard function for completing filenames,
_files
. If the style is unset up to three tags are offered,
‘globbed-files
’,‘directories
’ and ‘all-files
’, depending on
the types of files expected by the caller of _files
. The first two
(‘globbed-files
’ and ‘directories
’) are normally offered
together to make it easier to complete files in sub-directories.
The file-patterns
style provides alternatives to the default tags,
which are not used. Its value consists of elements of the form
‘pattern:
tag’; each string may contain any number of
such specifications separated by spaces.
The pattern is a pattern that is to be used to generate filenames.
Any occurrence of the sequence ‘%p
’ is replaced by any
pattern(s)
passed by the function calling _files
. Colons in the pattern must
be preceded by a backslash to make them distinguishable from the colon
before the tag. If more than one pattern is needed, the patterns
can be given inside braces, separated by commas.
The tags of all strings in the value will be offered by _files
and used when looking up other styles. Any tags in the same
word will be offered at the same time and before later words.
If no ‘:
tag’ is given the ‘files
’ tag will be used.
The tag may also be followed by an optional second colon and a
description, which will be used for the ‘%d
’ in the value of
the format
style (if that is set) instead of the default
description supplied by the completion function. The inclusion
of a description also gives precedence to associated options such as
for completion grouping so it can be used where files should be
separated.
For example, to make the rm
command first complete only names of
object files and then the names of all files if there is no matching
object file:
zstyle ':completion:*:*:rm:*:*' file-patterns \ '*.o:object-files' '%p:all-files'
To alter the default behaviour of file completion — offer files matching a pattern and directories on the first attempt, then all files — to offer only matching files on the first attempt, then directories, and finally all files:
zstyle ':completion:*' file-patterns \ '%p:globbed-files' '*(-/):directories' '*:all-files'
This works even where there is no special pattern: _files
matches
all files using the pattern ‘*
’ at the first step and stops when it
sees this pattern. Note also it will never try a pattern more than once
for a single completion attempt.
To separate directories into a separate group from the files but still
complete them at the first attempt, a description needs to be given.
Note that directories need to be explicitly excluded from the
globbed-files because ‘*
’ will match directories. For grouping, it
is also necessary to set the group-name
style.
zstyle ':completion:*' file-patterns \ '%p(^-/):globbed-files *(-/):directories:location'
During the execution of completion functions, the EXTENDED_GLOB
option is in effect, so the characters ‘#
’, ‘~
’ and ‘^
’ have
special meanings in the patterns.
file-sort
The standard filename completion function uses this style without a tag
to determine in which order the names should be listed; menu completion
will cycle through them in the same order. The possible
values are: ‘size
’ to sort by the size of the file;
‘links
’ to sort by the number of links to the file;
‘modification
’ (or ‘time
’ or ‘date
’) to sort by the last
modification time; ‘access
’ to sort by the last access time; and
‘inode
’ (or ‘change
’) to sort by the last inode change
time. If the style is set to any other value, or is unset, files will be
sorted alphabetically by name. If the value contains the string
‘reverse
’, sorting is done in the opposite order. If the value
contains the string ‘follow
’, timestamps are associated with the
targets of symbolic links; the default is to use the timestamps
of the links themselves.
file-split-chars
A set of characters that will cause all file completions for
the given context to be split at the point where any of the characters
occurs. A typical use is to set the style to :
; then everything
up to and including the last :
in the string so far is ignored when
completing files. As this is quite heavy-handed, it is usually
preferable to update completion functions for contexts where this
behaviour is useful.
filter
The ldap
plugin of email address completion (see _email_addresses
) uses
this style to specify
the attributes to match against when filtering entries. So for example, if
the style is set to ‘sn
’, matching is done against surnames. Standard
LDAP filtering is used so normal completion matching is bypassed. If this
style is not set, the LDAP plugin is skipped. You may also need to set the
command
style to specify how to connect to your LDAP server.
force-list
This forces a list of completions to be shown at any point where listing is
done, even in cases where the list would usually be suppressed.
For example, normally the list is only shown if
there are at least two different matches. By setting this style to
‘always
’, the list will always be shown, even if there is only a
single match that will immediately be accepted. The style may also
be set to a number. In this case the list will be shown if there are
at least that many matches, even if they would all insert the same
string.
This style is tested for the default tag as well as for each tag valid for the current completion. Hence the listing can be forced only for certain types of match.
format
If this is set for the descriptions
tag, its value is used as a
string to display above matches in completion lists. The sequence
‘%d
’ in this string will be replaced with a short description of
what these matches are. This string may also contain the output
attribute sequences understood by compadd -X
(see
Completion Widgets).
The style is tested with each tag valid for the current completion
before it is tested for the descriptions
tag. Hence different format
strings can be defined for different types of match.
Note also that some completer functions define additional
‘%
’-sequences. These are described for the completer functions that
make use of them.
Some completion functions display messages that may be customised by
setting this style for the messages
tag. Here, the ‘%d
’ is
replaced with a message given by the completion function.
Finally, the format string is looked up with the warnings
tag,
for use when no matches could be generated at all. In this case the
‘%d
’ is replaced with the descriptions for the matches that were
expected separated by spaces. The sequence ‘%D
’ is replaced with
the same descriptions separated by newlines.
It is possible to use printf-style field width specifiers with ‘%d
’
and similar escape sequences. This is handled by the zformat
builtin command from the zsh/zutil
module, see
The zsh/zutil Module.
gain-privileges
If set to true
, this style enables the use of commands like sudo
or doas
to gain extra privileges when retrieving information for
completion. This is only done when a command such as sudo
appears on
the command-line. To force the use of, e.g. sudo
or to override any
prefix that might be added due to gain-privileges
, the command
style can be used with a value that begins with a hyphen.
glob
This is used by the _expand
completer. If
it is set to ‘true’ (the default), globbing will be attempted on the
words resulting from a previous substitution (see the substitute
style) or else the original string from the line.
global
If this is set to ‘true’ (the default), the _expand_alias
completer and bindable command will try to expand global aliases.
group-name
The completion system can group different types of matches, which appear in separate lists. This style can be used to give the names of groups for particular tags. For example, in command position the completion system generates names of builtin and external commands, names of aliases, shell functions and parameters and reserved words as possible completions. To have the external commands and shell functions listed separately:
zstyle ':completion:*:*:-command-:*:commands' \ group-name commands zstyle ':completion:*:*:-command-:*:functions' \ group-name functions
As a consequence, any match with the same tag will be displayed in the same group.
If the name given is the empty string the name of the tag for the matches will be used as the name of the group. So, to have all different types of matches displayed separately, one can just set:
zstyle ':completion:*' group-name {No value for `dsq'}
All matches for which no group name is defined will be put in a group
named -default-
.
To display the group name in the output, see the format
style (q.v.)
under the descriptions
tag.
group-order
This style is additional to the group-name
style to specify the
order for display of the groups defined by that style (compare tag-order
,
which determines which completions appear at all). The groups named
are shown in the given order; any other groups
are shown in the order defined by the completion function.
For example, to have names of builtin commands, shell functions and external commands appear in that order when completing in command position:
zstyle ':completion:*:*:-command-:*:*' group-order \ builtins functions commands
groups
A list of names of UNIX groups. If this is not set,
group names are taken from the YP database or the file ‘/etc/group
’.
hidden
If this is set to ‘true’, matches for the given context
will not be listed, although
any description for the matches set with the format
style will be
shown. If it is set to ‘all
’, not even the description will be
displayed.
Note that the matches will still be completed; they are just not shown
in the list. To avoid having matches considered as possible
completions at all, the tag-order
style can be modified as described
below.
hosts
A list of names of hosts that should be completed. If this is not set,
hostnames are taken from the file ‘/etc/hosts
’.
hosts-ports
This style is used by commands that need or accept hostnames and
network ports. The strings in the value should be of the form
‘host:
port’. Valid ports are determined by the presence
of hostnames; multiple ports for the same host may appear.
ignore-line
This is tested for each tag valid for the current completion. If
it is set to ‘true’, none of the words that are already on the line
will be considered as possible completions. If it is set to
‘current
’, the word the cursor is on will not be considered as a
possible completion. The value ‘current-shown
’ is similar but only
applies if the list of completions is currently shown on the screen.
Finally, if the style is set to ‘other
’, all words on the line except
for the current one will be excluded from the possible completions.
The values ‘current
’ and ‘current-shown
’ are a bit like the
opposite of the accept-exact
style: only strings with
missing characters will be completed.
Note that you almost certainly don’t want to set this to ‘true’ or
‘other
’ for a general
context such as ‘:completion:*
’. This is because it would disallow
completion of, for example, options multiple times even if the command
in question accepts the option more than once.
ignore-parents
The style is tested without a tag by the function completing pathnames in order to determine whether to ignore the names of directories already mentioned in the current word, or the name of the current working directory. The value must include one or both of the following strings:
parent
The name of any directory whose path is already contained in the word on
the line is ignored. For example, when completing after foo/../
, the
directory foo
will not be considered a valid completion.
pwd
The name of the current working directory will not be completed; hence,
for example, completion after ../
will not use the name of the current
directory.
In addition, the value may include one or both of:
..
Ignore the specified directories only when the word on the line contains
the substring ‘../
’.
directory
Ignore the specified directories only when names of directories are completed, not when completing names of files.
Excluded values act in a similar fashion to values of the
ignored-patterns
style, so they can be restored to consideration by
the _ignored
completer.
ignored-patterns
A list of patterns; any trial completion matching one of the patterns
will be excluded from consideration. The
_ignored
completer can appear in the list of completers to
restore the ignored matches. This is a more configurable
version of the shell parameter $fignore
.
Note that the
EXTENDED_GLOB
option is set during the execution of completion
functions, so the characters ‘#
’, ‘~
’ and ‘^
’ have special
meanings in the patterns.
insert
This style is used by the _all_matches
completer to decide whether to
insert the list of all matches unconditionally instead of adding the
list as another match.
insert-ids
When completing process IDs, for example as arguments to the kill
and
wait
builtins the name of a
command may be converted to the appropriate process ID. A problem
arises when the process name typed is not unique. By default (or if this
style is set explicitly to ‘menu
’) the name will be converted
immediately to a set of possible IDs, and menu completion will be started
to cycle through them.
If the value of the style is ‘single
’,
the shell will wait until the user has typed enough to make the command
unique before converting the name to an ID; attempts at completion will
be unsuccessful until that point. If the value is any other
string, menu completion will be started when the string typed by the
user is longer than the common prefix to the corresponding IDs.
insert-sections
This style is used with tags of the form ‘manuals.
X’ when
completing names of manual pages. If set and the X in the tag name matches
the section number of the page being completed, the section number is inserted
along with the page name. For example, given
zstyle ':completion:*:manuals.*' insert-sections true
man ssh_<TAB>
may be completed to man 5 ssh_config
.
The value may also be set to one of ‘prepend
’, or ‘suffix
’.
‘prepend
’ behaves the same as ‘true’ as in the above example, while
‘suffix
’ would complete man ssh_<TAB>
as man ssh_config.5
.
This is especially useful in conjunction with separate-sections
, as
it ensures that the page requested of man
corresponds to the one
displayed in the completion listing when there are multiple pages with the
same name (e.g., printf(1)
and printf(3)
).
The default for this style is ‘false’.
insert-tab
If this is set to ‘true’, the completion system will insert a TAB character (assuming that was used to start completion) instead of performing completion when there is no non-blank character to the left of the cursor. If it is set to ‘false’, completion will be done even there.
The value may also contain the substrings ‘pending
’ or
‘pending=
val’. In this case, the typed character will be
inserted instead of starting completion when there is unprocessed input
pending. If a val is given, completion will not be done if there
are at least that many characters of unprocessed input. This is often
useful when pasting characters into a terminal. Note
however, that it relies on the $PENDING
special parameter from the
zsh/zle
module being set properly which is not guaranteed on all
platforms.
The default value of this style is ‘true’ except for completion within
vared
builtin command where it is ‘false’.
insert-unambiguous
This is used by the _match
and _approximate
completers.
These completers are often used with menu completion since the word typed
may bear little resemblance to the final completion.
However, if this style is ‘true’, the completer will start menu
completion only if it could find no unambiguous initial string at
least as long as the original string typed by the user.
In the case of the _approximate
completer, the completer
field in the context will already have been set to one of
correct-
num or approximate-
num, where num is the
number of errors that were accepted.
In the case of the _match
completer, the style may also be set to
the string ‘pattern
’. Then the pattern on the line is left
unchanged if it does not match unambiguously.
keep-prefix
This style is used by the _expand
completer. If it is ‘true’, the
completer will try to keep a prefix containing a tilde or parameter
expansion. Hence, for example, the string ‘~/f*
’ would be expanded to
‘~/foo
’ instead of ‘/home/user/foo
’. If the style is set to
‘changed
’ (the default), the prefix will only be left unchanged if
there were other changes between the expanded words and the original
word from the command line. Any other value forces the prefix to be
expanded unconditionally.
The behaviour of _expand
when this style is ‘true’ is to cause _expand
to give up when a single expansion with the restored prefix is the same
as the original; hence any remaining completers may be called.
known-hosts-files
This style should contain a list of files to search for host names and
(if the use-ip
style is set) IP addresses in a format compatible with
ssh known_hosts
files. If it is not set, the files
/etc/ssh/ssh_known_hosts
and ~/.ssh/known_hosts
are used.
last-prompt
This is a more flexible form of the ALWAYS_LAST_PROMPT
option.
If it is ‘true’, the completion system will try to return the cursor to
the previous command line after displaying a completion list. It is
tested for all tags valid for the current completion, then the
default
tag. The cursor will be moved back to the
previous line if this style is ‘true’ for all types of match. Note
that unlike the ALWAYS_LAST_PROMPT
option this is independent of the
numeric argument.
list
This style is used by the _history_complete_word
bindable command.
If it is set to ‘true’ it has no effect. If it is set to ‘false’
matches will not be listed. This overrides the setting of the options
controlling listing behaviour, in particular AUTO_LIST
. The context
always starts with ‘:completion:history-words
’.
list-colors
If the zsh/complist
module is loaded, this style can be used to set
color specifications. This mechanism replaces the use of the
ZLS_COLORS
and ZLS_COLOURS
parameters described in
The zsh/complist Module, but the syntax is the same.
If this style is set for the default
tag, the strings in the value
are taken as specifications that are to be used everywhere. If it is
set for other tags, the specifications are used only for matches of
the type described by the tag. For this to work best, the group-name
style must be set to an empty string.
In addition to setting styles for specific tags, it is also possible to
use group names specified explicitly by the group-name
tag together
with the ‘(group)
’ syntax allowed by the ZLS_COLORS
and
ZLS_COLOURS
parameters and simply using the default
tag.
It is possible to use any color specifications already set up for the GNU
version of the ls
command:
zstyle ':completion:*:default' list-colors \ ${(s.:.)LS_COLORS}
The default colors are the same as for the GNU ls
command and can be
obtained by setting the style to an empty string (i.e. {No value for `dsq'}
).
list-dirs-first
This is used by file completion and corresponds to a particular
setting of the file-patterns
style.
If set, the default directories to be completed
are listed separately from and before completion for other files.
list-grouped
If this style is ‘true’ (the default), the completion system will try to
make certain completion listings more compact by grouping matches.
For example, options for commands that have the same description (shown
when the verbose
style is set to ‘true’) will appear as a single
entry. However, menu selection can be used to cycle through all the
matches.
list-packed
This is tested for each tag valid in the current context as well as the
default
tag. If it is set to ‘true’, the corresponding matches
appear in listings as if the LIST_PACKED
option were set. If it is
set to ‘false’, they are listed normally.
list-prompt
If this style is set for the default
tag,
completion lists that don’t fit on the screen can be scrolled (see
The zsh/complist Module). The value, if not the empty string, will be displayed after every
screenful and the shell will prompt for a key press; if the style is
set to the empty string,
a default prompt will be used.
The value may contain the escape sequences:
‘%l
’ or ‘%L
’, which will be replaced by the number of the last line
displayed and the total number of lines; ‘%m
’ or ‘%M
’,
the number of the last match shown and the total number of
matches; and ‘%p
’ and ‘%P
’, ‘Top
’
when at the beginning of the list, ‘Bottom
’ when at the end and the
position shown as a percentage of the total length otherwise. In each
case the form with the uppercase letter will be replaced by a string of fixed
width, padded to the right with spaces, while the lowercase form will
be replaced by a variable width string. As in other prompt strings, the
escape sequences ‘%S
’, ‘%s
’, ‘%B
’, ‘%b
’, ‘%U
’,
‘%u
’ for entering and leaving the display modes
standout, bold and underline, and ‘%F
’, ‘%f
’, ‘%K
’, ‘%k
’ for
changing the foreground background colour, are also available, as is the form
‘%{
...%}
’ for enclosing escape sequences which display with zero
(or, with a numeric argument, some other) width.
After deleting this prompt the variable LISTPROMPT
should be unset for
the removal to take effect.
list-rows-first
This style is tested in the same way as the list-packed
style and
determines whether matches are to be listed in a rows-first fashion as
if the LIST_ROWS_FIRST
option were set.
list-separator
The value of this style is used in completion listing to separate the
string to complete from a description when possible (e.g. when
completing options). It defaults to ‘-
-
’ (two hyphens).
list-suffixes
This style is used by the function that completes filenames. If it is ‘true’, and completion is attempted on a string containing multiple partially typed pathname components, all ambiguous components will be shown. Otherwise, completion stops at the first ambiguous component.
local
This is for use with functions that complete URLs for which the corresponding files are available directly from the file system. Its value should consist of three strings: a hostname, the path to the default web pages for the server, and the directory name used by a user placing web pages within their home area.
For example:
zstyle ':completion:*' local toast \ /var/http/public/toast public_html
Completion after ‘http://toast/stuff/
’ will look for files in the
directory /var/http/public/toast/stuff
, while completion after
‘http://toast/~yousir/
’ will look for files in the directory
~yousir/public_html
.
mail-directory
If set, zsh will assume that mailbox files can be found in
the directory specified. It defaults to ‘~/Mail
’.
match-original
This is used by the _match
completer. If it is set to
only
, _match
will try to generate matches without inserting a
‘*
’ at the cursor position. If set to any other non-empty value,
it will first try to generate matches without inserting the ‘*
’
and if that yields no matches, it will try again with the ‘*
’
inserted. If it is unset or set to the empty string, matching will
only be performed with the ‘*
’ inserted.
matcher
This style is tested separately for each tag valid in the current
context. Its value is placed before any match specifications given by the
matcher-list
style so can override them via the use of an x:
specification. The value should be in the form described in
Completion Matching Control. For examples of this, see the description of the tag-order
style.
For notes comparing the use of this and the matcher-list
style, see
under the description of the tag-order
style.
matcher-list
This style can be set to a list of match specifications that are to be applied everywhere. Match specifications are described in Completion Matching Control. The completion system will try them one after another for each completer selected. For example, to try first simple completion and, if that generates no matches, case-insensitive completion:
zstyle ':completion:*' matcher-list {No value for `dsq'} 'm:{a-zA-Z}={A-Za-z}'
By default each specification replaces the previous one; however, if a
specification is prefixed with +
, it is added to the existing list.
Hence it is possible to create increasingly general specifications
without repetition:
zstyle ':completion:*' matcher-list \ {No value for `dsq'} '+m:{a-z}={A-Z}' '+m:{A-Z}={a-z}'
It is possible to create match specifications valid for particular
completers by using the third field of the context. This applies only
to completers that override the global matcher-list, which as of this
writing includes only _prefix
and _ignored
. For example, to
use the completers _complete
and _prefix
but allow
case-insensitive completion only with _complete
:
zstyle ':completion:*' completer _complete _prefix zstyle ':completion:*:complete:*:*:*' matcher-list \ {No value for `dsq'} 'm:{a-zA-Z}={A-Za-z}'
User-defined names, as explained for the completer
style, are
available. This makes it possible to try the same completer more than
once with different match specifications each time. For example, to try
normal completion without a match specification, then normal completion
with case-insensitive matching, then correction, and finally
partial-word completion:
zstyle ':completion:*' completer \ _complete _correct _complete:foo zstyle ':completion:*:complete:*:*:*' matcher-list \ {No value for `dsq'} 'm:{a-zA-Z}={A-Za-z}' zstyle ':completion:*:foo:*:*:*' matcher-list \ 'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*'
If the style is unset in any context no match specification is applied.
Note also that some completers such as _correct
and _approximate
do not use the match specifications at all, though these completers will
only ever be called once even if the matcher-list
contains more than
one element.
Where multiple specifications are useful, note that the entire
completion is done for each element of matcher-list
, which can
quickly reduce the shell’s performance. As a rough rule of thumb,
one to three strings will give acceptable performance. On the other
hand, putting multiple space-separated values into the same string does
not have an appreciable impact on performance.
If there is no current matcher or it is empty, and the option
NO_CASE_GLOB
is in effect, the matching for files is performed
case-insensitively in any case. However, any matcher must
explicitly specify case-insensitive matching if that is required.
For notes comparing the use of this and the matcher
style, see
under the description of the tag-order
style.
max-errors
This is used by the _approximate
and _correct
completer functions
to determine the maximum number of errors to allow. The completer will try
to generate completions by first allowing one error, then two errors, and
so on, until either a match or matches were found or the maximum number of
errors given by this style has been reached.
If the value for this style contains the string ‘numeric
’, the
completer function will take any numeric argument as the
maximum number of errors allowed. For example, with
zstyle ':completion:*:approximate:::' max-errors 2 numeric
two errors are allowed if no numeric argument is given, but with
a numeric argument of six (as in ‘ESC-6 TAB
’), up to six
errors are accepted. Hence with a value of ‘0 numeric
’, no correcting
completion will be attempted unless a numeric argument is given.
If the value contains the string ‘not-numeric
’, the completer
will not try to generate corrected
completions when given a numeric argument, so in this case the number given
should be greater than zero. For example, ‘2 not-numeric
’ specifies that
correcting completion with two errors will usually be performed, but if a
numeric argument is given, correcting completion will not be
performed.
The default value for this style is ‘2 numeric
’.
max-matches-width
This style is used to determine the trade off between the width of the
display used for matches and the width used for their descriptions when
the verbose
style is in effect. The value gives the number of
display columns to reserve for the matches. The default is half the
width of the screen.
This has the most impact when several matches have the same description and so will be grouped together. Increasing the style will allow more matches to be grouped together; decreasing it will allow more of the description to be visible.
menu
If this is ‘true’ in the context of any of the tags defined
for the current completion menu completion will be used. The value for
a specific tag will take precedence over that for the ‘default
’ tag.
If none of the values found in this way is ‘true’ but at least
one is set to ‘auto
’, the shell behaves as if the AUTO_MENU
option is set.
If one of the values is explicitly set to ‘false’, menu
completion will be explicitly turned off, overriding the
MENU_COMPLETE
option and other settings.
In the form ‘yes=
num’, where ‘yes
’ may be any of the
‘true’ values (‘yes
’, ‘true
’, ‘on
’ and ‘1
’),
menu completion will be turned on if there are at least num matches.
In the form ‘yes=long
’, menu completion will be turned on
if the list does not fit on the screen. This does not activate menu
completion if the widget normally only lists completions, but menu
completion can be activated in that case with the value ‘yes=long-list
’
(Typically, the value ‘select=long-list
’ described later is more
useful as it provides control over scrolling.)
Similarly, with any of the ‘false’ values (as in ‘no=10
’), menu
completion will not be used if there are num or more matches.
The value of this widget also controls menu selection, as implemented by
the zsh/complist
module. The following values may appear either
alongside or instead of the values above.
If the value contains the string ‘select
’, menu selection
will be started unconditionally.
In the form ‘select=
num’, menu selection will only be started if
there are at least num matches. If the values for more than one
tag provide a number, the smallest number is taken.
Menu selection can be turned off explicitly by defining a value
containing the string‘no-select
’.
It is also possible to start menu selection only if the list of
matches does not fit on the screen by using the value
‘select=long
’. To start menu selection even if the current widget
only performs listing, use the value ‘select=long-list
’.
To turn on menu completion or menu selection when there are a certain
number of matches or the list of matches does not fit on the
screen, both of ‘yes=
’ and ‘select=
’ may be given twice, once
with a number and once with ‘long
’ or ‘long-list
’.
Finally, it is possible to activate two special modes of menu selection.
The word ‘interactive
’ in the value causes interactive mode
to be entered immediately when menu selection is started; see
The zsh/complist Module
for a description of interactive mode. Including the string
‘search
’ does the same for incremental search mode. To select backward
incremental search, include the string ‘search-backward
’.
muttrc
If set, gives the location of the mutt configuration file. It defaults
to ‘~/.muttrc
’.
numbers
This is used with the jobs
tag. If it is ‘true’, the shell will
complete job numbers instead of the shortest unambiguous prefix
of the job command text. If the value is a number, job numbers will
only be used if that many words from the job descriptions are required to
resolve ambiguities. For example, if the value is ‘1
’, strings will
only be used if all jobs differ in the first word on their command lines.
old-list
This is used by the _oldlist
completer. If it is set to ‘always
’,
then standard widgets which perform listing will retain the current list of
matches, however they were generated; this can be turned off explicitly
with the value ‘never
’, giving the behaviour without the _oldlist
completer. If the style is unset, or any other value, then the existing
list of completions is displayed if it is not already; otherwise, the
standard completion list is generated; this is the default behaviour of
_oldlist
. However, if there is an old list and this style contains
the name of the completer function that generated the list, then the
old list will be used even if it was generated by a widget which does
not do listing.
For example, suppose you type ^Xc
to use the _correct_word
widget, which generates a list of corrections for the word under the
cursor. Usually, typing ^D
would generate a standard list of
completions for the word on the command line, and show that. With
_oldlist
, it will instead show the list of corrections already
generated.
As another example consider the _match
completer: with the
insert-unambiguous
style set to ‘true’ it inserts only a common prefix
string, if there is any. However, this may remove parts of the original
pattern, so that further completion could produce more matches than on the
first attempt. By using the _oldlist
completer and setting this style
to _match
, the list of matches generated on the first attempt will be
used again.
old-matches
This is used by the _all_matches
completer to decide if an old
list of matches should be used if one exists. This is selected by one of
the ‘true’ values or by the string ‘only
’. If
the value is ‘only
’, _all_matches
will only use an old list
and won’t have any effect on the list of matches currently being
generated.
If this style is set it is generally unwise to call the _all_matches
completer unconditionally. One possible use is for either this style or
the completer
style to be defined with the -e
option to
zstyle
to make the style conditional.
old-menu
This is used by the _oldlist
completer. It controls how menu
completion behaves when a completion has already been inserted and the
user types a standard completion key such as TAB
. The default
behaviour of _oldlist
is that menu completion always continues
with the existing list of completions. If this style is set to
‘false’, however, a new completion is started if the old list was
generated by a different completion command; this is the behaviour without
the _oldlist
completer.
For example, suppose you type ^Xc
to generate a list of corrections,
and menu completion is started in one of the usual ways. Usually, or with
this style set to ‘false’, typing TAB
at this point would start
trying to complete the line as it now appears. With _oldlist
, it
instead continues to cycle through the list of corrections.
original
This is used by the _approximate
and _correct
completers to decide if the original string should be added as
a possible completion. Normally, this is done only if there are
at least two possible corrections, but if this style is set to ‘true’, it
is always added. Note that the style will be examined with the
completer field in the context name set to correct-
num or
approximate-
num, where num is the number of errors that
were accepted.
packageset
This style is used when completing arguments of the Debian ‘dpkg
’
program. It contains an override for the default package set
for a given context. For example,
zstyle ':completion:*:complete:dpkg:option--status-1:*' \ packageset avail
causes available packages, rather than only installed packages,
to be completed for ‘dpkg -
-status
’.
path
The function that completes color names uses this style with the
colors
tag. The value should be the pathname of a file
containing color names in the format of an X11 rgb.txt
file. If
the style is not set but this file is found in one of various standard
locations it will be used as the default.
path-completion
This is used by filename completion. By default, filename completion
examines all components of a path to see if there are completions of
that component. For example, /u/b/z
can be completed to
/usr/bin/zsh
. Explicitly setting this style to ‘false’ inhibits this
behaviour for path components up to the /
before the cursor; this
overrides the setting of accept-exact-dirs
.
Even with the style set to ‘false’, it is still possible to complete
multiple paths by setting the option COMPLETE_IN_WORD
and moving the
cursor back to the first component in the path to be completed. For
example, /u/b/z
can be completed to /usr/bin/zsh
if the cursor is
after the /u
.
pine-directory
If set, specifies the directory containing PINE mailbox files. There is no default, since recursively searching this directory is inconvenient for anyone who doesn’t use PINE.
ports
A list of Internet service names (network ports) to complete. If this is
not set, service names are taken from the file ‘/etc/services
’.
prefix-hidden
This is used for certain completions which share a common prefix, for example command options beginning with dashes. If it is ‘true’, the prefix will not be shown in the list of matches.
The default value for this style is ‘false’.
prefix-needed
This style is also relevant for matches with a common prefix. If it is set to ‘true’ this common prefix must be typed by the user to generate the matches.
The style is applicable to the options
, signals
, jobs
,
functions
, and parameters
completion tags.
For command options, this means that the initial ‘-
’, ‘+
’, or
‘-
-
’ must be typed explicitly before option names will be
completed.
For signals, an initial ‘-
’ is required before signal names will
be completed.
For jobs, an initial ‘%
’ is required before job names will be
completed.
For function and parameter names, an initial ‘_
’ or ‘.
’ is
required before function or parameter names starting with those
characters will be completed.
The default value for this style is ‘false’ for function
and
parameter
completions, and ‘true’ otherwise.
preserve-prefix
This style is used when completing path names. Its value should be a
pattern matching an initial prefix of the word to complete that should
be left unchanged under all circumstances. For example, on some Unices
an initial ‘//
’ (double slash) has a special meaning; setting
this style to the string ‘//
’ will preserve it. As another example,
setting this style to ‘?:/
’ under Cygwin would allow completion
after ‘a:/...
’ and so on.
range
This is used by the _history
completer and the
_history_complete_word
bindable command to decide which words
should be completed.
If it is a single number, only the last N words from the history will be completed.
If it is a range of the form ‘max:
slice’,
the last slice words will be completed; then if that
yields no matches, the slice words before those will be tried and
so on. This process stops either when at least one match has been
found, or max words have been tried.
The default is to complete all words from the history at once.
recursive-files
If this style is set, its value is an array of patterns to be
tested against ‘$PWD/
’: note the trailing slash, which allows
directories in the pattern to be delimited unambiguously by including
slashes on both sides. If an ordinary file completion fails
and the word on the command line does not yet have a directory part to its
name, the style is retrieved using the same tag as for the completion
just attempted, then the elements tested against $PWD/
in turn.
If one matches, then the shell reattempts completion by prepending the word
on the command line with each directory in the expansion of **/*(/)
in turn. Typically the elements of the style will be set to restrict
the number of directories beneath the current one to a manageable
number, for example ‘*/.git/*
’.
For example,
zstyle ':completion:*' recursive-files '*/zsh/*'
If the current directory is /home/pws/zsh/Src
, then
zle_tr<TAB>
can be completed to Zle/zle_tricky.c
.
regular
This style is used by the _expand_alias
completer and bindable
command. If set to ‘true’ (the default), regular aliases will be
expanded but only in command position. If it is set to ‘false’,
regular aliases will never be expanded. If it is set to ‘always
’,
regular aliases will be expanded even if not in command position.
rehash
If this is set when completing external commands, the internal
list (hash) of commands will be updated for each search by issuing
the rehash
command. There is a speed penalty for this which
is only likely to be noticeable when directories in the path have
slow file access.
remote-access
If set to ‘false’, certain commands will be prevented from making
Internet connections to retrieve remote information. This includes the
completion for the CVS
command.
It is not always possible to know if connections are in fact to a remote site, so some may be prevented unnecessarily.
remove-all-dups
The _history_complete_word
bindable command and the _history
completer use this to decide if all duplicate matches should be
removed, rather than just consecutive duplicates.
select-prompt
If this is set for the default
tag, its
value will be displayed during menu selection (see the menu
style
above) when the completion list does not fit on the screen as a
whole. The same escapes as for the list-prompt
style are
understood, except that the numbers refer to the match or line the mark is
on. A default prompt is used when the value is the empty string.
select-scroll
This style is tested for the default
tag and determines how a
completion list is scrolled during a menu selection (see the menu
style above) when the completion list does not fit on the screen as a
whole. If the value is ‘0
’ (zero), the list is scrolled by
half-screenfuls; if it is a positive integer, the list is scrolled by the
given number of lines; if it is a negative number, the list is scrolled by a
screenful minus the absolute value of the given number of lines.
The default is to scroll by single lines.
separate-sections
This style is used with the manuals
tag when completing names of
manual pages. If it is ‘true’, entries for different sections are
added separately using tag names of the form ‘manuals.
X’,
where X is the section number. When the group-name
style is
also in effect, pages from different sections will appear separately.
This style is also used similarly with the words
style when
completing words for the dict command. It allows words from different
dictionary databases to be added separately. See also insert-sections
.
The default for this style is ‘false’.
show-ambiguity
If the zsh/complist
module is loaded, this style can be used to
highlight the first ambiguous character in completion lists. The
value is either a color indication such as those supported by the
list-colors
style or, with a value of ‘true’, a default of
underlining is selected. The highlighting is only applied if the
completion display strings correspond to the actual matches.
show-completer
Tested whenever a new completer is tried. If it is ‘true’, the completion system outputs a progress message in the listing area showing what completer is being tried. The message will be overwritten by any output when completions are found and is removed after completion is finished.
single-ignored
This is used by the _ignored
completer when there is only one match.
If its value is ‘show
’, the single match will be
displayed but not inserted. If the value is ‘menu
’, then the single
match and the original string are both added as matches and menu completion
is started, making it easy to select either of them.
sort
This allows the standard ordering of matches to be overridden.
If its value is ‘true
’ or ‘false
’, sorting is enabled or disabled.
Additionally the values associated with the ‘-o
’ option to compadd
can
also be listed: match
, nosort
, numeric
, reverse
. If it is not
set for the context, the standard behaviour of the calling widget is used.
The style is tested first against the full context including the tag, and if that fails to produce a value against the context without the tag.
In many cases where a calling widget explicitly selects a particular ordering
in lieu of the default, a value of ‘true
’ is not honoured. An example of
where this is not the case is for command history where the default of sorting
matches chronologically may be overridden by setting the style to ‘true’.
In the _expand
completer, if it is set to
‘true’, the expansions generated will always be sorted. If it is set
to ‘menu
’, then the expansions are only sorted when they are offered
as single strings but not in the string containing all possible
expansions.
special-dirs
Normally, the completion code will not produce the directory names
‘.
’ and ‘..
’ as possible completions. If this style is set to
‘true’, it will add both ‘.
’ and ‘..
’ as possible completions;
if it is set to ‘..
’, only ‘..
’ will be added.
The following example sets special-dirs
to ‘..
’ when the
current prefix is empty, is a single ‘.
’, or consists only of a path
beginning with ‘../
’. Otherwise the value is ‘false’.
zstyle -e ':completion:*' special-dirs \ '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'
squeeze-slashes
If set to ‘true’, sequences of slashes in filename paths (for example in
‘foo//bar
’) will be treated as a single slash. This is the usual
behaviour of UNIX paths. However, by default the file completion
function behaves as if there were a ‘*
’ between the slashes.
stop
If set to ‘true’, the _history_complete_word
bindable
command will stop once when reaching the beginning or end of the
history. Invoking _history_complete_word
will then wrap around to
the opposite end of the history. If this style is set to ‘false’ (the
default), _history_complete_word
will loop immediately as in a
menu completion.
strip-comments
If set to ‘true’, this style causes non-essential comment text to be removed from completion matches. Currently it is only used when completing e-mail addresses where it removes any display name from the addresses, cutting them down to plain user@host form.
subst-globs-only
This is used by the _expand
completer. If it is set to ‘true’,
the expansion will only be used if it resulted from globbing; hence,
if expansions resulted from the use of the substitute
style
described below, but these were not further changed by globbing, the
expansions will be rejected.
The default for this style is ‘false’.
substitute
This boolean style controls whether the _expand
completer will
first try to expand all substitutions in the string (such as
‘$(
...)
’ and ‘${
...}
’).
The default is ‘true’.
suffix
This is used by the _expand
completer if the word starts with a
tilde or contains a parameter expansion. If it is set to ‘true’, the
word will only be expanded if it doesn’t have a suffix, i.e. if it is
something like ‘~foo
’ or ‘$foo
’ rather than ‘~foo/
’ or
‘$foo/bar
’, unless that suffix itself contains characters eligible
for expansion. The default for this style is ‘true’.
tag-order
This provides a mechanism for sorting how the tags available in a particular context will be used.
The values for the style are sets of space-separated lists of tags.
The tags in each value will be tried at the same time; if no match is
found, the next value is used. (See the file-patterns
style for
an exception to this behavior.)
For example:
zstyle ':completion:*:complete:-command-:*:*' tag-order \ 'commands functions'
specifies that completion in command position first offers external commands and shell functions. Remaining tags will be tried if no completions are found.
In addition to tag names, each string in the value may take one of the following forms:
-
If any value consists of only a hyphen, then only the tags specified in the other values are generated. Normally all tags not explicitly selected are tried last if the specified tags fail to generate any matches. This means that a single value consisting only of a single hyphen turns off completion.
!
tags...A string starting with an exclamation mark specifies names of tags that are not to be used. The effect is the same as if all other possible tags for the context had been listed.
:
label ...Here, tag is one of the standard tags and label is an
arbitrary name. Matches are generated as normal but the name label
is used in contexts instead of tag. This is not useful in words
starting with !
.
If the label starts with a hyphen, the tag is prepended to the label to form the name used for lookup. This can be used to make the completion system try a certain tag more than once, supplying different style settings for each attempt; see below for an example.
:
label:
descriptionAs before, but description
will replace the ‘%d
’ in
the value of the format
style instead of the default description
supplied by the completion function. Spaces in the description must
be quoted with a backslash. A ‘%d
’ appearing
in description is replaced with the description given by the
completion function.
In any of the forms above the tag may be a pattern or several
patterns in the form ‘{
pat1,
pat2...}
’. In this
case all matching tags will be used except
for any given explicitly in the same string.
One use of these features is to try one tag more than once, setting other styles differently on each attempt, but still to use all the other tags without having to repeat them all. For example, to make completion of function names in command position ignore all the completion functions starting with an underscore the first time completion is tried:
zstyle ':completion:*:*:-command-:*:*' tag-order \ 'functions:-non-comp *' functions zstyle ':completion:*:functions-non-comp' \ ignored-patterns '_*'
On the first attempt, all tags will be offered but the functions
tag
will be replaced by functions-non-comp
. The ignored-patterns
style
is set for this tag to exclude functions starting with an underscore.
If there are no matches, the second value of the
tag-order
style is used which completes functions using the default
tag, this time presumably including all function names.
The matches for one tag can be split into different groups. For example:
zstyle ':completion:*' tag-order \ 'options:-long:long\ options options:-short:short\ options options:-single-letter:single\ letter\ options' zstyle ':completion:*:options-long' \ ignored-patterns '[-+](|-|[^-]*)' zstyle ':completion:*:options-short' \ ignored-patterns '--*' '[-+]?' zstyle ':completion:*:options-single-letter' \ ignored-patterns '???*'
With the group-names
style set, options beginning with
‘-
-
’, options beginning with a single ‘-
’ or ‘+
’ but
containing multiple characters, and single-letter options will be
displayed in separate groups with different descriptions.
Another use of patterns is to
try multiple match specifications one after another. The
matcher-list
style offers something similar, but it is tested very
early in the completion system and hence can’t be set for single
commands nor for more specific contexts. Here is how to
try normal completion without any match specification and, if that
generates no matches, try again with case-insensitive matching, restricting
the effect to arguments of the command foo
:
zstyle ':completion:*:*:foo:*:*' tag-order '*' '*:-case' zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'
First, all the tags offered when completing after foo
are tried using
the normal tag name. If that generates no matches, the second value of
tag-order
is used, which tries all tags again except that this time
each has -case
appended to its name for lookup of styles. Hence this
time the value for the matcher
style from the second call to zstyle
in the example is used to make completion case-insensitive.
It is possible to use the -e
option of the zstyle
builtin
command to specify conditions for the use of particular tags. For
example:
zstyle -e '*:-command-:*' tag-order ' if [[ -n $PREFIX$SUFFIX ]]; then reply=( ) else reply=( - ) fi'
Completion in command position will be attempted only if the string
typed so far is not empty. This is tested using the PREFIX
special parameter; see
Completion Widgets
for a description of parameters which are special inside completion widgets.
Setting reply
to an empty array provides the default
behaviour of trying all tags at once; setting it to an
array containing only a hyphen disables the use of all tags and hence of
all completions.
If no tag-order
style has been defined for a context, the strings
‘(|*-)argument-* (|*-)option-* values
’ and ‘options
’ plus all
tags offered by the completion function will be used to provide a
sensible default behavior that causes arguments (whether normal command
arguments or arguments of options) to be completed before option names for
most commands.
urls
This is used together with the urls
tag by
functions completing URLs.
If the value consists of more than one string, or if the only string does not name a file or directory, the strings are used as the URLs to complete.
If the value contains only one string which is the name of a normal file the URLs are taken from that file (where the URLs may be separated by white space or newlines).
Finally, if the only string in the value names a directory, the
directory hierarchy rooted at this directory gives the completions. The
top level directory should be the file access method, such as
‘http
’, ‘ftp
’, ‘bookmark
’ and so on. In many cases the next
level of directories will be a filename. The directory hierarchy can
descend as deep as necessary.
For example,
zstyle ':completion:*' urls ~/.urls mkdir -p ~/.urls/ftp/ftp.zsh.org/pub
allows completion of all the components of the URL
ftp://ftp.zsh.org/pub
after suitable commands such as
‘netscape
’ or ‘lynx
’. Note, however, that access methods and
files are completed separately, so if the hosts
style is set hosts
can be completed without reference to the urls
style.
See the description in the function _urls
itself
for more information (e.g. ‘more $^fpath/_urls(N)
’).
use-cache
If this is set, the completion caching layer is activated for any completions
which use it (via the _store_cache
, _retrieve_cache
, and
_cache_invalid
functions). The directory containing the cache
files can be changed with the cache-path
style.
use-compctl
If this style is set to a string not equal to false
, 0
,
no
, and off
, the completion system may use any completion
specifications defined with the compctl
builtin command. If the
style is unset, this is done only if the zsh/compctl
module
is loaded. The string may also contain the substring ‘first
’ to
use completions defined with ‘compctl -T
’, and the substring
‘default
’ to use the completion defined with ‘compctl -D
’.
Note that this is only intended to smooth the transition from
compctl
to the new completion system and may disappear in the
future.
Note also that the definitions from compctl
will only be used if
there is no specific completion function for the command in question. For
example, if there is a function _foo
to complete arguments to the
command foo
, compctl
will never be invoked for foo
.
However, the compctl
version will be tried if foo
only uses
default completion.
use-ip
By default, the function _hosts
that completes host names strips
IP addresses from entries read from host databases such as NIS and
ssh files. If this style is ‘true’, the corresponding IP addresses
can be completed as well. This style is not use in any context
where the hosts
style is set; note also it must be set before
the cache of host names is generated (typically the first completion
attempt).
users
This may be set to a list of usernames to be completed. If it is not set all usernames will be completed. Note that if it is set only that list of users will be completed; this is because on some systems querying all users can take a prohibitive amount of time.
users-hosts
The values of this style should be of the form
‘user@
host’ or ‘user:
host’. It is used for
commands that need pairs of
user- and hostnames. These commands will complete usernames from this
style (only), and will restrict subsequent hostname completion to hosts
paired with that user in one of the values of the style.
It is possible to group values for sets of commands which allow a remote
login, such as rlogin
and ssh
, by using the my-accounts
tag.
Similarly, values for sets of commands which usually refer to the
accounts of other people, such as talk
and finger
, can be
grouped by using the other-accounts
tag. More ambivalent commands
may use the accounts
tag.
users-hosts-ports
Like users-hosts
but used for commands like telnet
and
containing strings of the form ‘user@
host:
port’.
verbose
If set, as it is by default, the completion listing is more verbose. In particular many commands show descriptions for options if this style is ‘true’.
word
This is used by the _list
completer, which prevents the insertion of
completions until a second completion attempt when the line has not
changed. The normal way of finding out if the line has changed is to
compare its entire contents between the two occasions. If this style is
‘true’, the comparison is instead performed only on the current word.
Hence if completion is performed on another word with the same contents,
completion will not be delayed.