(zsh.info.gz) Completion System Configuration
Info Catalog
(zsh.info.gz) Initialization
(zsh.info.gz) Completion System
(zsh.info.gz) Control Functions
20.3 Completion System Configuration
====================================
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.
20.3.1 Overview
---------------
When completion is attempted somewhere on the command line the
completion system first works out the context. 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).
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. This is used to look up
_styles_, context-sensitive options that can be used to configure the
completion system. The context used for lookup may vary during the same
call to the completion system.
The context string always consists of a fixed set of fields, separated
by colons and with a leading colon before the first, in the form
:completion:FUNCTION:COMPLETER:COMMAND:ARGUMENT:tag. These have the
following meaning:
* The literal string 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.
* The FUNCTION, if completion is called from a named widget rather
than through the normal completion system. Typically this is
blank, but it is set by special widgets such as predict-on and the
various functions in the Widget directory of the distribution to
the name of that function, often in an abbreviated form.
* The COMPLETER currently active, the name of the function without
the leading underscore and with other underscores converted to
hyphens. A 'completer' is in overall control of how completion is
to be performed; '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.
* The COMMAND or a special -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.
* The ARGUMENT; this indicates which command line or option argument
we are completing. For command arguments this generally takes the
form 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 TAG. As described previously, tags are used to discriminate
between the types of matches a completion function can generate in
a certain context. Any completion function may use any tag name it
likes, but a list of the more common ones is given below.
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.
Styles determine such things as how the matches are generated, similarly
to shell options but with much more control. They can have any number
of strings as their value. They are defined with the zstyle builtin
command ( The zsh/zutil Module).
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 may be matched as a pattern, and the
name of the style itself, which must be given exactly.
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
context 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. More precisely, strings are
preferred over patterns (for example, ':completion::complete:foo' is
more specific than ':completion::complete:*'), and longer patterns are
preferred over shorter patterns.
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.
20.3.2 Standard Tags
--------------------
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
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
jobs
for jobs (as listed by the 'jobs' builtin)
interfaces
for network interfaces
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
manuals
for names of manual pages
mailboxes
for e-mail folders
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
other-files
for the names of any non-directory files. This is used instead of
all-files when the list-dirs-first style is in effect.
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
20.3.3 Standard Styles
----------------------
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.
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.
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. 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. If the description given here
contains itself a '%d', that is replaced with the description
supplied by the completion function.
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.
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.
filter
This is used by the LDAP plugin for e-mail address completion 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 following
sequences to specify output attributes, Prompt Expansion:
'%B', '%S', '%U', '%F', '%K' and their lower case counterparts, as
well as '%{...%}'. '%F', '%K' and '%{...%}' take arguments in the
same form as prompt expansion. Note that the %G sequence is not
available; an argument to '%{' should be used instead.
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.
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 ''
All matches for which no group name is defined will be put in a
group named -default-.
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.
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'.
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-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.
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 prefix
argument.
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.
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. '').
list-dirs-first
This is used by file completion. If set, directories to be
completed are listed separately from and before completion for
other files, regardless of tag ordering. In addition, the tag
other-files is used in place of all-files for the remaining files,
to indicate that no directories are presented with that tag.
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-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.
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).
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 added to any match specifications given by
the matcher-list style. It should be in the form described in
Completion Matching Control.
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 '' '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 '' '+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. For example,
to use the completers _complete and _prefix but only allow
case-insensitive completion with _complete:
zstyle ':completion:*' completer _complete _prefix
zstyle ':completion:*:complete:*' matcher-list \
'' '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 \
'' '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.
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 a 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 singe 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 was 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 'manual.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. The default for this style is
'false'.
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
Many completion widgets call _description at some point which
decides whether the matches are added sorted or unsorted (often
indirectly via _wanted or _requested). This style can be set
explicitly to one of the usual true or false values as an override.
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.
If the calling widget explicitly requests unsorted matches, this is
usually honoured. However, the default (unsorted) behaviour of
completion for the command history 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.
TAG: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.
TAG:LABEL:DESCRIPTION
As 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.
Info Catalog
(zsh.info.gz) Initialization
(zsh.info.gz) Completion System
(zsh.info.gz) Control Functions
automatically generated by
info2html