The key sequence ESC h
is normally bound by ZLE to execute the
run-help
widget (see
Zsh Line Editor). This invokes the run-help
command with the command word from the
current input line as its argument. By default, run-help
is an alias
for the man
command, so this often fails when the command word is a
shell builtin or a user-defined function. By redefining the run-help
alias, one can improve the on-line help provided by the shell.
The helpfiles
utility, found in the Util
directory of the
distribution, is a Perl program that can be used to process the zsh manual
to produce a separate help file for each shell builtin and for many other
shell features as well. The autoloadable run-help
function, found in
Functions/Misc
, searches for these helpfiles and performs several
other tests to produce the most complete help possible for the command.
Help files are installed by default to a subdirectory of /usr/share/zsh
or /usr/local/share/zsh
.
To create your own help files with helpfiles
, choose or create a
directory where the individual command help files will reside. For
example, you might choose ~/zsh_help
. If you unpacked the zsh
distribution in your home directory, you would use the commands:
mkdir ~/zsh_help perl ~/zsh-5.9/Util/helpfiles ~/zsh_help
The HELPDIR
parameter tells run-help
where to look for the help
files. When unset, it uses the default installation path.
To use your own set of help files, set this to the appropriate path
in one of your startup files:
HELPDIR=~/zsh_help
To use the run-help
function, you need to add lines something
like the following to your .zshrc
or equivalent startup file:
unalias run-help autoload run-help
Note that in order for ‘autoload run-help
’ to work, the run-help
file must be in one of the directories named in your fpath
array (see
Parameters Used By The Shell). This should already be the case if you have a standard zsh
installation; if it is not, copy Functions/Misc/run-help
to an
appropriate directory.
If you frequently edit your zsh functions, or periodically update your zsh
installation to track the latest developments, you may find that function
digests compiled with the zcompile
builtin are frequently out of date
with respect to the function source files. This is not usually a problem,
because zsh always looks for the newest file when loading a function, but
it may cause slower shell startup and function loading. Also, if a digest
file is explicitly used as an element of fpath
, zsh won’t check whether
any of its source files has changed.
The zrecompile
autoloadable function, found in Functions/Misc
, can
be used to keep function digests up to date.
zrecompile
[ -qt
] [ name ... ]zrecompile
[ -qt
] -p
arg ... [ -
-
arg ... ]This tries to find *.zwc
files and automatically re-compile them if at
least one of the original files is newer than the compiled file. This
works only if the names stored in the compiled files are full paths or are
relative to the directory that contains the .zwc
file.
In the first form, each name is the name of a compiled file or a
directory containing *.zwc
files that should be checked. If no
arguments are given, the directories and *.zwc
files in fpath
are
used.
When -t
is given, no compilation is performed, but a return status of
zero (true) is set if there are files that need to be re-compiled and
non-zero (false) otherwise. The -q
option quiets the chatty output
that describes what zrecompile
is doing.
Without the -t
option, the return status is zero if all files that
needed re-compilation could be compiled and non-zero if compilation for at
least one of the files failed.
If the -p
option is given, the args are interpreted as one
or more sets of arguments for zcompile
, separated by ‘-
-
’.
For example:
zrecompile -p \ -R ~/.zshrc -- \ -M ~/.zcompdump -- \ ~/zsh/comp.zwc ~/zsh/Completion/*/_*
This compiles ~/.zshrc
into ~/.zshrc.zwc
if that doesn’t exist or
if it is older than ~/.zshrc
. The compiled file will be marked for
reading instead of mapping. The same is done for ~/.zcompdump
and
~/.zcompdump.zwc
, but this compiled file is marked for mapping. The
last line re-creates the file ~/zsh/comp.zwc
if any of the files
matching the given pattern is newer than it.
Without the -p
option, zrecompile
does not create function digests
that do not already exist, nor does it add new functions to the digest.
The following shell loop is an example of a method for creating function
digests for all functions in your fpath
, assuming that you have write
permission to the directories:
for ((i=1; i <= $#fpath; ++i)); do dir=$fpath[i] zwc=${dir:t}.zwc if [[ $dir == (.|..) || $dir == (.|..)/* ]]; then continue fi files=($dir/*(N-.)) if [[ -w $dir:h && -n $files ]]; then files=(${${(M)files%/*/*}#/}) if ( cd $dir:h && zrecompile -p -U -z $zwc $files ); then fpath[i]=$fpath[i].zwc fi fi done
The -U
and -z
options are appropriate for functions in the default
zsh installation fpath
; you may need to use different options for your
personal function directories.
Once the digests have been created and your fpath
modified to refer to
them, you can keep them up to date by running zrecompile
with no
arguments.
The large number of possible combinations of keyboards, workstations,
terminals, emulators, and window systems makes it impossible for zsh to
have built-in key bindings for every situation. The zkbd
utility,
found in Functions/Misc
, can help you quickly create key bindings for your
configuration.
Run zkbd
either as an autoloaded function, or as a shell script:
zsh -f ~/zsh-5.9/Functions/Misc/zkbd
When you run zkbd
, it first asks you to enter your terminal type; if
the default it offers is correct, just press return. It then asks you to
press a number of different keys to determine characteristics of your
keyboard and terminal; zkbd
warns you if it finds anything out of the
ordinary, such as a Delete key that sends neither ^H
nor ^?
.
The keystrokes read by zkbd
are recorded as a definition for an
associative array named key
, written to a file in the subdirectory
.zkbd
within either your HOME
or ZDOTDIR
directory. The name
of the file is composed from the TERM
, VENDOR
and OSTYPE
parameters, joined by hyphens.
You may read this file into your .zshrc
or another startup file with
the ‘source
’ or ‘.
’ commands, then reference the key
parameter
in bindkey commands, like this:
source ${ZDOTDIR:-$HOME}/.zkbd/$TERM-$VENDOR-$OSTYPE [[ -n ${key[Left]} ]] && bindkey "${key[Left]}" backward-char [[ -n ${key[Right]} ]] && bindkey "${key[Right]}" forward-char # etc.
Note that in order for ‘autoload zkbd
’ to work, the zkdb
file must
be in one of the directories named in your fpath
array (see
Parameters Used By The Shell). This should already be the case if you have a standard zsh
installation; if it is not, copy Functions/Misc/zkbd
to an
appropriate directory.
Occasionally you may encounter what appears to be a bug in the shell, particularly if you are using a beta version of zsh or a development release. Usually it is sufficient to send a description of the problem to one of the zsh mailing lists (see Mailing Lists), but sometimes one of the zsh developers will need to recreate your environment in order to track the problem down.
The script named reporter
, found in the Util
directory of the
distribution, is provided for this purpose. (It is also possible to
autoload reporter
, but reporter
is not installed in fpath
by default.) This script outputs a detailed dump of the shell state,
in the form of another script that can be read with ‘zsh -f
’ to
recreate that state.
To use reporter
, read the script into your shell with the ‘.
’
command and redirect the output into a file:
. ~/zsh-5.9/Util/reporter > zsh.report
You should check the zsh.report
file for any sensitive information
such as passwords and delete them by hand before sending the script to the
developers. Also, as the output can be voluminous, it’s best to wait for
the developers to ask for this information before sending it.
You can also use reporter
to dump only a subset of the shell state.
This is sometimes useful for creating startup files for the first time.
Most of the output from reporter is far more detailed than usually is
necessary for a startup file, but the aliases
, options
, and
zstyles
states may be useful because they include only changes from
the defaults. The bindings
state may be useful if you have created
any of your own keymaps, because reporter
arranges to dump the keymap
creation commands as well as the bindings for every keymap.
As is usual with automated tools, if you create a startup file with
reporter
, you should edit the results to remove unnecessary commands.
Note that if you’re using the new completion system, you should not
dump the functions
state to your startup files with reporter
; use
the compdump
function instead (see
Completion System).
reporter
[ state ... ] ¶Print to standard output the indicated subset of the current shell state. The state arguments may be one or more of:
all
Output everything listed below.
aliases
Output alias definitions.
bindings
Output ZLE key maps and bindings.
completion
Output old-style compctl
commands.
New completion is covered by functions
and zstyles
.
functions
Output autoloads and function definitions.
limits
Output limit
commands.
options
Output setopt
commands.
styles
Same as zstyles
.
variables
Output shell parameter assignments, plus export
commands for any environment variables.
zstyles
Output zstyle
commands.
If the state is omitted, all
is assumed.
With the exception of ‘all
’, every state can be abbreviated by
any prefix, even a single letter; thus a
is the same as aliases
,
z
is the same as zstyles
, etc.
add-zsh-hook
[ -L
| -dD
] [ -Uzk
] hook functionSeveral functions are special to the shell, as described in the section
Special Functions, Functions,
in that they are automatically called at specific points during shell execution.
Each has an associated array consisting of names of functions to be
called at the same point; these are so-called ‘hook functions’.
The shell function add-zsh-hook
provides a simple way of adding or
removing functions from the array.
hook is one of chpwd
, periodic
, precmd
, preexec
,
zshaddhistory
, zshexit
, or zsh_directory_name
,
the special functions in question. Note that zsh_directory_name
is called in a different way from the other functions, but may
still be manipulated as a hook.
function is name of an ordinary shell function. If no options are given this will be added to the array of functions to be executed in the given context. Functions are invoked in the order they were added.
If the option -L
is given, the current values for the hook arrays
are listed with typeset
.
If the option -d
is given, the function is removed from
the array of functions to be executed.
If the option -D
is given, the function is treated as a pattern
and any matching names of functions are removed from the array of
functions to be executed.
The options -U
, -z
and -k
are passed as arguments to
autoload
for function. For functions contributed with zsh, the
options -Uz
are appropriate.
add-zle-hook-widget
[ -L
| -dD
] [ -Uzk
] hook widgetnameSeveral widget names are special to the line editor, as described in the section
Special Widgets, Zle Widgets,
in that they are automatically called at specific points during editing.
Unlike function hooks, these do not use a predefined array of other names
to call at the same point; the shell function add-zle-hook-widget
maintains a similar array and arranges for the special widget to invoke
those additional widgets.
hook is one of isearch-exit
, isearch-update
,
line-pre-redraw
, line-init
, line-finish
, history-line-set
,
or keymap-select
, corresponding to each of the special widgets
zle-isearch-exit
, etc. The special widget names are also accepted
as the hook argument.
widgetname is the name of a ZLE widget. If no options are given this is added to the array of widgets to be invoked in the given hook context. Widgets are invoked in the order they were added, with
zle
widgetname-Nw -f "nolast" -- "$@"
Note that this means that the ‘WIDGET
’ special parameter tracks the
widgetname when the widget function is called, rather than tracking
the name of the corresponding special hook widget.
If the option -d
is given, the widgetname is removed from
the array of widgets to be executed.
If the option -D
is given, the widgetname is treated as a pattern
and any matching names of widgets are removed from the array.
If widgetname does not name an existing widget when added to the
array, it is assumed that a shell function also named widgetname is
meant to provide the implementation of the widget. This name is therefore
marked for autoloading, and the options -U
, -z
and -k
are
passed as arguments to autoload
as with add-zsh-hook
. The
widget is also created with ‘zle -N
widgetname’ to cause the
corresponding function to be loaded the first time the hook is called.
The arrays of widgetname are currently maintained in zstyle
contexts, one for each hook context, with a style of ‘widgets
’.
If the -L
option is given, this set of styles is listed with
‘zstyle -L
’. This implementation may change, and the special widgets
that refer to the styles are created only if add-zle-hook-widget
is
called to add at least one widget, so if this function is used for any
hooks, then all hooks should be managed only via this function.