26.2 Utilities

26.2.1 Accessing On-Line Help

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.

26.2.2 Recompiling Functions

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.

26.2.3 Keyboard Definition

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.

26.2.4 Dumping Shell State

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.

26.2.5 Manipulating Hook Functions

add-zsh-hook [ -L | -dD ] [ -Uzk ] hook function

Several 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 widgetname

Several 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.