Accessing On-Line Help¶

The key sequence ESC h is normally bound by ZLE to execute the run-help widget (see zshzle(1)). 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.

There may already be a directory of help files on your system; look in /usr/share/zsh or /usr/local/share/zsh and subdirectories below those, or ask your system administrator.

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
cd ~/zsh_help
man zshall | colcrt - | \ 
perl ~/zsh-5.0.2/Util/helpfiles

Next, 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
HELPDIR=~/zsh_help

The HELPDIR parameter tells run-help where to look for the help files. If your system already has a help file directory installed, set HELPDIR to the path of that directory instead.

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 zshparam(1)). 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.

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 args [ -- args ... ]

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.

zrecompile -p \ 


           -R ~/.zshrc -- \ 


           -M ~/.zcompdump -- \ 


           ~/zsh/comp.zwc ~/zsh/Completion/*/_*

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.

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.0.2/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 zshparam(1)). 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.

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 zsh(1)), 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.0.2/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 zshcompsys(1)).

reporter [ state ... ]

Print to standard output the indicated subset of the current shell state. The state arguments may be one or more of:

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.

Manipulating Hook Functions¶

add-zsh-hook [-dD] hook function

Several functions are special to the shell, as described in the section SPECIAL FUNCTIONS, see zshmisc(1), in that they are automatic called at a specific point 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.

Installation¶

The system works by means of a hook function that is called every time the directory changes. To install the system, autoload the required functions and use the add-zsh-hook function described above:

autoload -Uz chpwd_recent_dirs cdr add-zsh-hook
add-zsh-hook chpwd chpwd_recent_dirs

Now every time you change directly interactively, no matter which command you use, the directory to which you change will be remembered in most-recent-first order.

Use¶

All direct user interaction is via the cdr function.

The argument to cdr is a number N corresponding to the Nth most recently changed-to directory. 1 is the immediately preceding directory; the current directory is remembered but is not offered as a destination. Note that if you have multiple windows open 1 may refer to a directory changed to in another window; you can avoid this by having per-terminal files for storing directory as described for the recent-dirs-file style below.

If you set the recent-dirs-default style described below cdr will behave the same as cd if given a non-numeric argument, or more than one argument. The recent directory list is updated just the same however you change directory.

If the argument is omitted, 1 is assumed. This is similar to pushd's behaviour of swapping the two most recent directories on the stack.

Completion for the argument to cdr is available if compinit has been run; menu selection is recommended, using:

zstyle ':completion:*:*:cdr:*:*' menu selection

to allow you to cycle through recent directories; the order is preserved, so the first choice is the most recent directory before the current one. The verbose style is also recommended to ensure the directory is shown; this style is on by default so no action is required unless you have changed it.

Options¶

The behaviour of cdr may be modified by the following options.

-l

lists the numbers and the corresponding directories in abbreviated form (i.e. with ~ substitution reapplied), one per line. The directories here are not quoted (this would only be an issue if a directory name contained a newline). This is used by the completion system.

-r

sets the variable reply to the current set of directories. Nothing is printed and the directory is not changed.

-e

allows you to edit the list of directories, one per line. The list can be edited to any extent you like; no sanity checking is performed. Completion is available. No quoting is necessary (except for newlines, where I have in any case no sympathy); directories are in unabbreviated from and contain an absolute path, i.e. they start with /. Usually the first entry should be left as the current directory.

Configuration¶

Configuration is by means of the styles mechanism that should be familiar from completion; if not, see the description of the zstyle command in see zshmodules(1). The context for setting styles should be ':chpwd:*' in case the meaning of the context is extended in future, for example:

zstyle ':chpwd:*' recent-dirs-max 0

sets the value of the recent-dirs-max style to 0. In practice the style name is specific enough that a context of '*' should be fine.

An exception is recent-dirs-insert, which is used exclusively by the completion system and so has the usual completion system context (':completion:*' if nothing more specific is needed), though again '*' should be fine in practice.

recent-dirs-default

If true, and the command is expecting a recent directory index, and either there is more than one argument or the argument is not an integer, then fall through to "cd". This allows the lazy to use only one command for directory changing. Completion recognises this, too; see recent-dirs-insert for how to control completion when this option is in use.

recent-dirs-file

The file where the list of directories is saved. The default is ${ZDOTDIR:-$HOME}/.chpwd-recent-dirs, i.e. this is in your home directory unless you have set the variable ZDOTDIR to point somewhere else. Directory names are saved in $'...' quoted form, so each line in the file can be supplied directly to the shell as an argument.

zstyle ':chpwd:*' recent-dirs-file \ 
~/.chpwd-recent-dirs-${TTY##*/} +

zstyle -e ':chpwd:*' recent-dirs-file pick-recent-dirs-file
pick-recent-dirs-file() {


  if [[ $PWD = ~/text/writing(|/*) ]]; then


    reply=(~/.chpwd-recent-dirs-writing)


  else


    reply=(+)


  fi
}

recent-dirs-insert

Used by completion. If recent-dirs-default is true, then setting this to true causes the actual directory, rather than its index, to be inserted on the command line; this has the same effect as using the corresponding index, but makes the history clearer and the line easier to edit. With this setting, if part of an argument was already typed, normal directory completion rather than recent directory completion is done; this is because recent directory completion is expected to be done by cycling through entries menu fashion.

recent-dirs-max

The maximum number of directories to save to the file. If this is zero or negative there is no maximum. The default is 20. Note this includes the current directory, which isn't offered, so the highest number of directories you will be offered is one less than the maximum.

recent-dirs-prune

This style is an array determining what directories should (or should not) be added to the recent list. Elements of the array can include:

recent-dirs-pushd

If set to true, cdr will use pushd instead of cd to change the directory, so the directory is saved on the directory stack. As the directory stack is completely separate from the list of files saved by the mechanism used in this file there is no obvious reason to do this.

Use with dynamic directory naming¶

It is possible to refer to recent directories using the dynamic directory name syntax by using the supplied function zsh_directory_name_cdr a hook:

autoload -Uz add-zsh-hook
add-zsh-hook -Uz zsh_directory_name zsh_directory_name_cdr

When this is done, ~[1] will refer to the most recent directory other than $PWD, and so on. Completion after ~[... also works.

Details of directory handling¶

This section is for the curious or confused; most users will not need to know this information.

Recent directories are saved to a file immediately and hence are preserved across sessions. Note currently no file locking is applied: the list is updated immediately on interactive commands and nowhere else (unlike history), and it is assumed you are only going to change directory in one window at once. This is not safe on shared accounts, but in any case the system has limited utility when someone else is changing to a different set of directories behind your back.

To make this a little safer, only directory changes instituted from the command line, either directly or indirectly through shell function calls (but not through subshells, evals, traps, completion functions and the like) are saved. Shell functions should use cd -q or pushd -q to avoid side effects if the change to the directory is to be invisible at the command line. See the contents of the function chpwd_recent_dirs for more details.

Quickstart¶

To get this feature working quickly (including colors), you can do the following (assuming, you loaded vcs_info properly - see above):

zstyle ':vcs_info:*' actionformats \ 


    '%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{3}|%F{1}%a%F{5}]%f '
zstyle ':vcs_info:*' formats       \ 


    '%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{5}]%f '
zstyle ':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F{1}:%F{3}%r'
precmd () { vcs_info }
PS1='%F{5}[%F{2}%n%F{5}] %F{3}%3~ ${vcs_info_msg_0_}%f%# '

Obviously, the last two lines are there for demonstration. You need to call vcs_info from your precmd function. Once that is done you need a single quoted '${vcs_info_msg_0_}' in your prompt.

To be able to use '${vcs_info_msg_0_}' directly in your prompt like this, you will need to have the PROMPT_SUBST option enabled.

Now call the vcs_info_printsys utility from the command line:

% vcs_info_printsys
## list of supported version control backends:
## disabled systems are prefixed by a hash sign (#)
bzr
cdv
cvs
darcs
fossil
git
hg
mtn
p4
svk
svn
tla
## flavours (cannot be used in the enable or disable styles; they
## are enabled and disabled with their master [git-svn -> git])
## they *can* be used in contexts: ':vcs_info:git-svn:*'.
git-p4
git-svn
hg-git
hg-hgsubversion
hg-hgsvn

You may not want all of these because there is no point in running the code to detect systems you do not use. So there is a way to disable some backends altogether:

zstyle ':vcs_info:*' disable bzr cdv darcs mtn svk tla

You may also pick a few from that list and enable only those:

zstyle ':vcs_info:*' enable git cvs svn

If you rerun vcs_info_printsys after one of these commands, you will see the backends listed in the disable style (or backends not in the enable style - if you used that) marked as disabled by a hash sign. That means the detection of these systems is skipped completely. No wasted time there.

Configuration¶

The vcs_info feature can be configured via zstyle.

First, the context in which we are working:

:vcs_info:vcs-string:user-context:repo-root-name

vcs-string

is one of: git, git-svn, git-p4, hg, hg-git, hg-hgsubversion, hg-hgsvn, darcs, bzr, cdv, mtn, svn, cvs, svk, tla, p4 or fossil. When hooks are active the hooks name is added after a `+'. (See Hooks in vcs_info below.)

user-context

is a freely configurable string, assignable by the user as the first argument to vcs_info (see its description below).

repo-root-name

is the name of a repository in which you want a style to match. So, if you want a setting specific to /usr/src/zsh, with that being a CVS checkout, you can set repo-root-name to zsh to make it so.

There are three special values for vcs-string: The first is named -init-, that is in effect as long as there was no decision what VCS backend to use. The second is -preinit-; it is used before vcs_info is run, when initializing the data exporting variables. The third special value is formats and is used by the vcs_info_lastmsg for looking up its styles.

The initial value of repo-root-name is -all- and it is replaced with the actual name, as soon as it is known. Only use this part of the context for defining the formats, actionformats or branchformat styles, as it is guaranteed that repo-root-name is set up correctly for these only. For all other styles, just use '*' instead.

There are two pre-defined values for user-context:

default

the one used if none is specified

command

used by vcs_info_lastmsg to lookup its styles

You can of course use ':vcs_info:*' to match all VCSs in all user-contexts at once.

This is a description of all styles that are looked up.

formats

A list of formats, used when actionformats is not used (which is most of the time).

actionformats

A list of formats, used if there is a special action going on in your current repository; like an interactive rebase or a merge conflict.

branchformat

Some backends replace %b in the formats and actionformats styles above, not only by a branch name but also by a revision number. This style lets you modify how that string should look.

nvcsformats

These "formats" are exported when we didn't detect a version control system for the current directory or vcs_info was disabled. This is useful if you want vcs_info to completely take over the generation of your prompt. You would do something like PS1='${vcs_info_msg_0_}' to accomplish that.

hgrevformat

hg uses both a hash and a revision number to reference a specific changeset in a repository. With this style you can format the revision string (see branchformat) to include either or both. It's only useful when get-revision is true. Note, the full 40-character revision id is not available (except when using the use-simple option) because executing hg more than once per prompt is too slow; you may customize this behavior using hooks.

max-exports

Defines the maximum number of vcs_info_msg_*_ variables vcs_info will export.

enable

A list of backends you want to use. Checked in the -init- context. If this list contains an item called NONE no backend is used at all and vcs_info will do nothing. If this list contains ALL, vcs_info will use all known backends. Only with ALL in enable will the disable style have any effect. ALL and NONE are case insensitive.

disable

A list of VCSs you don't want vcs_info to test for repositories (checked in the -init- context, too). Only used if enable contains ALL.

disable-patterns

A list of patterns that are checked against $PWD. If a pattern matches, vcs_info will be disabled. This style is checked in the :vcs_info:-init-:*:-all- context.

zstyle ':vcs_info:*' disable-patterns "$HOME/.zsh(|/*)"

use-quilt

If enabled, the quilt support code is active in `addon' mode. See Quilt Support for details.

quilt-standalone

If enabled, `standalone' mode detection is attempted if no VCS is active in a given directory. See Quilt Support for details.

quilt-patch-dir

Overwrite the value of the $QUILT_PATCHES environment variable. See Quilt Support for details.

quiltcommand

When quilt itself is called in quilt support the value of this style is used as the command name.

check-for-changes

If enabled, this style causes the %c and %u format escapes to show when the working directory has uncommitted changes. The strings displayed by these escapes can be controlled via the stagedstr and unstagedstr styles. The only backends that currently support this option are git and hg (hg only supports unstaged).

stagedstr

This string will be used in the %c escape if there are staged changes in the repository.

unstagedstr

This string will be used in the %u escape if there are unstaged changes in the repository.

command

This style causes vcs_info to use the supplied string as the command to use as the VCS's binary. Note, that setting this in ':vcs_info:*' is not a good idea.

zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git

use-server

This is used by the Perforce backend (p4) to decide if it should contact the Perforce server to find out if a directory is managed by Perforce. This is the only reliable way of doing this, but runs the risk of a delay if the server name cannot be found. If the server (more specifically, the host:port pair describing the server) cannot be contacted, its name is put into the associative array vcs_info_p4_dead_servers and is not contacted again during the session until it is removed by hand. If you do not set this style, the p4 backend is only usable if you have set the environment variable P4CONFIG to a file name and have corresponding files in the root directories of each Perforce client. See comments in the function VCS_INFO_detect_p4 for more detail.

use-simple

If there are two different ways of gathering information, you can select the simpler one by setting this style to true; the default is to use the not-that-simple code, which is potentially a lot slower but might be more accurate in all possible cases. This style is used by the bzr and hg backends. In the case of hg it will invoke the external hexdump program to parse the binary dirstate cache file; this method will not return the local revision number.

get-revision

If set to true, vcs_info goes the extra mile to figure out the revision of a repository's work tree (currently for the git and hg backends, where this kind of information is not always vital). For git, the hash value of the currently checked out commit is available via the %i expansion. With hg, the local revision number and the corresponding global hash are available via %i.

get-mq

If set to true, the hg backend will look for a Mercurial Queue (mq) patch directory. Information will be available via the `%m' replacement.

get-bookmarks

If set to true, the hg backend will try to get a list of current bookmarks. They will be available via the `%m' replacement.

use-prompt-escapes

Determines if we assume that the assembled string from vcs_info includes prompt escapes. (Used by vcs_info_lastmsg.)

debug

Enable debugging output to track possible problems. Currently this style is only used by vcs_info's hooks system.

hooks

A list style that defines hook-function names. See Hooks in vcs_info below for details.

The default values for these styles in all contexts are:

formats

" (%s)-[%b]%u%c-"

actionformats

" (%s)-[%b|%a]%u%c-"

branchformat

"%b:%r" (for bzr, svn, svk and hg)

nvcsformats

""

hgrevformat

"%r:%h"

max-exports

2

enable

ALL

disable

(empty list)

disable-patterns

(empty list)

check-for-changes

false

stagedstr

(string: "S")

unstagedstr

(string: "U")

command

(empty string)

use-server

false

use-simple

false

get-revision

false

get-mq

true

get-bookmarks

false

use-prompt-escapes

true

debug

false

hooks

(empty list)

use-quilt

false

quilt-standalone

false

quilt-patch-dir

empty - use $QUILT_PATCHES

quiltcommand

quilt

In normal formats and actionformats the following replacements are done:

%s

The VCS in use (git, hg, svn, etc.).

%b

Information about the current branch.

%a

An identifier that describes the action. Only makes sense in actionformats.

%i

The current revision number or identifier. For hg the hgrevformat style may be used to customize the output.

%c

The string from the stagedstr style if there are staged changes in the repository.

%u

The string from the unstagedstr style if there are unstaged changes in the repository.

%R

The base directory of the repository.

%r

The repository name. If %R is /foo/bar/repoXY, %r is repoXY.

%S

A subdirectory within a repository. If $PWD is /foo/bar/repoXY/beer/tasty, %S is beer/tasty.

%m

A "misc" replacement. It is at the discretion of the backend to decide what this replacement expands to. It is currently used by the hg and git backends to display patch information from the mq and stgit extensions.

In branchformat these replacements are done:

%b

The branch name.

%r

The current revision number or the hgrevformat style for hg.

In hgrevformat these replacements are done:

%r

The current local revision number.

%h

The current global revision identifier.

In patch-format and nopatch-format these replacements are done:

%p

The name of the top-most applied patch (applied-string).

%u

The number of unapplied patches (unapplied-string).

%n

The number of applied patches.

%c

The number of unapplied patches.

%a

The number of all patches.

%g

The names of active mq guards (hg backend).

%G

The number of active mq guards (hg backend).

Not all VCS backends have to support all replacements. For nvcsformats no replacements are performed at all, it is just a string.

Oddities¶

If you want to use the %b (bold off) prompt expansion in formats, which expands %b itself, use %%b. That will cause the vcs_info expansion to replace %%b with %b, so that zsh's prompt expansion mechanism can handle it. Similarly, to hand down %b from branchformat, use %%%%b. Sorry for this inconvenience, but it cannot be easily avoided. Luckily we do not clash with a lot of prompt expansions and this only needs to be done for those.

Quilt Support¶

Quilt is not a version control system, therefore this is not implemented as a backend. It can help keeping track of a series of patches. People use it to keep a set of changes they want to use on top of software packages (which is tightly integrated into the package build process - the Debian project does this for a large number of packages). Quilt can also help individual developers keep track of their own patches on top of real version control systems.

The vcs_info integration tries to support both ways of using quilt by having two slightly different modes of operation: `addon' mode and `standalone' mode).

For `addon' mode to become active vcs_info must have already detected a real version control system controlling the directory. If that is the case, a directory that holds quilt's patches needs to be found. That directory is configurable via the `QUILT_PATCHES' environment variable. If that variable exists its value is used, otherwise the value `patches' is assumed. The value from $QUILT_PATCHES can be overwritten using the `quilt-patches' style. (Note: you can use vcs_info to keep the value of $QUILT_PATCHES correct all the time via the post-quilt hook).

When the directory in question is found, quilt is assumed to be active. To gather more information, vcs_info looks for a directory called `.pc'; Quilt uses that directory to track its current state. If this directory does not exist we know that quilt has not done anything to the working directory (read: no patches have been applied yet).

If patches are applied, vcs_info will try to find out which. If you want to know which patches of a series are not yet applied, you need to activate the get-unapplied style in the appropriate context.

vcs_info allows for very detailed control over how the gathered information is presented (see the below sections, Styles and Hooks in vcs_info), all of which are documented below. Note there are a number of other patch tracking systems that work on top of a certain version control system (like stgit for git, or mq for hg); the configuration for systems like that are generally configured the same way as the quilt support.

If the quilt support is working in `addon' mode, the produced string is available as a simple format replacement (%Q to be precise), which can be used in formats and actionformats; see below for details).

If, on the other hand, the support code is working in `standalone' mode, vcs_info will pretend as if quilt were an actual version control system. That means that the version control system identifier (which otherwise would be something like `svn' or `cvs') will be set to `-quilt-'. This has implications on the used style context where this identifier is the second element. vcs_info will have filled in a proper value for the "repository's" root directory and the string containing the information about quilt's state will be available as the `misc' replacement (and %Q for compatibility with `addon' mode.

What is left to discuss is how `standalone' mode is detected. The detection itself is a series of searches for directories. You can have this detection enabled all the time in every directory that is not otherwise under version control. If you know there is only a limited set of trees where you would like vcs_info to try and look for Quilt in `standalone' mode to minimise the amount of searching on every call to vcs_info, there are a number of ways to do that:

Essentially, `standalone' mode detection is controlled by a style called `quilt-standalone'. It is a string style and its value can have different effects. The simplest values are: `always' to run detection every time vcs_info is run, and `never' to turn the detection off entirely.

If the value of quilt-standalone is something else, it is interpreted differently. If the value is the name of a scalar variable the value of that variable is checked and that value is used in the same `always'/`never' way as described above.

If the value of quilt-standalone is an array, the elements of that array are used as directory names under which you want the detection to be active.

If quilt-standalone is an associative array, the keys are taken as directory names under which you want the detection to be active, but only if the corresponding value is the string `true'.

Last, but not least, if the value of quilt-standalone is the name of a function, the function is called without arguments and the return value decides whether detection should be active. A `0' return value is true; a non-zero return value is interpreted as false.

Note, if there is both a function and a variable by the name of quilt-standalone, the function will take precedence.

Function Descriptions (Public API)¶

vcs_info [user-context]

The main function, that runs all backends and assembles all data into ${vcs_info_msg_*_}. This is the function you want to call from precmd if you want to include up-to-date information in your prompt (see Variable description below). If an argument is given, that string will be used instead of default in the user-context field of the style context.

vcs_info_hookadd

Statically registers a number of functions to a given hook. The hook needs to be given as the first argument; what follows is a list of hook-function names to register to the hook. The `+vi-' prefix needs to be left out here. See Hooks in vcs_info below for details.

vcs_info_hookdel

Remove hook-functions from a given hook. The hook needs to be given as the first non-option argument; what follows is a list of hook-function names to un-register from the hook. If `-a' is used as the first argument, all occurances of the functions are unregistered. Otherwise only the last occurance is removed (if a function was registered to a hook more than once) . The `+vi-' prefix needs to be left out here. See Hooks in vcs_info below for details.

vcs_info_lastmsg

Outputs the last ${vcs_info_msg_*_} value. Takes into account the value of the use-prompt-escapes style in ':vcs_info:formats:command:-all-'. It also only prints max-exports values.

vcs_info_printsys [user-context]

Prints a list of all supported version control systems. Useful to find out possible contexts (and which of them are enabled) or values for the disable style.

vcs_info_setsys

Initializes vcs_info's internal list of available backends. With this function, you can add support for new VCSs without restarting the shell.

All functions named VCS_INFO_* are for internal use only.

Variable Description¶

${vcs_info_msg_N_} (Note the trailing underscore)

Where N is an integer, e.g., vcs_info_msg_0_. These variables are the storage for the informational message the last vcs_info call has assembled. These are strongly connected to the formats, actionformats and nvcsformats styles described above. Those styles are lists. The first member of that list gets expanded into ${vcs_info_msg_0_}, the second into ${vcs_info_msg_1_} and the Nth into ${vcs_info_msg_N-1_}. These parameters are exported into the environment. (See the max-exports style above.)

All variables named VCS_INFO_* are for internal use only.

Hooks in vcs_info¶

Hooks are places in vcs_info where you can run your own code. That code can communicate with the code that called it and through that, change the system's behaviour.

For configuration, hooks change the style context:

:vcs_info:vcs-string+hook-name:user-context:repo-root-name

To register functions to a hook, you need to list them in the hooks style in the appropriate context.

Example:

zstyle ':vcs_info:*+foo:*' hooks bar baz

This registers functions to the hook `foo' for all backends. In order to avoid namespace problems, all registered function names are prepended by a `+vi-', so the actual functions called for the `foo' hook are `+vi-bar' and `+vi-baz'.

If you would like to register a function to a hook regardless of the current context, you may use the vcs_info_hookadd function. To remove a function that was added like that, the vcs_info_hookdel function can be used.

If something seems weird, you can enable the `debug' boolean style in the proper context and the hook-calling code will print what it tried to execute and whether the function in question existed.

When you register more than one function to a hook, all functions are executed one after another until one function returns non-zero or until all functions have been called. Context-sensitive hook functions are executed before statically registered ones (the ones added by vcs_info_hookadd).

You may pass data between functions via an associative array, user_data. For example:

+vi-git-myfirsthook(){


    user_data[myval]=$myval
}
+vi-git-mysecondhook(){


    # do something with ${user_data[myval]}
}

There are a number of variables that are special in hook contexts:

ret

The return value that the hooks system will return to the caller. The default is an integer `zero'. If and how a changed ret value changes the execution of the caller depends on the specific hook. See the hook documentation below for details.

hook_com

An associated array which is used for bidirectional communication from the caller to hook functions. The used keys depend on the specific hook.

context

The active context of the hook. Functions that wish to change this variable should make it local scope first.

vcs

The current VCS after it was detected. The same values as in the enable/disable style are used. Available in all hooks except start-up.

Finally, the full list of currently available hooks:

start-up

Called after starting vcs_info but before the VCS in this directory is determined. It can be used to deactivate vcs_info temporarily if necessary. When ret is set to 1, vcs_info aborts and does nothing; when set to 2, vcs_info sets up everything as if no version control were active and exits.

pre-get-data

Same as start-up but after the VCS was detected.

gen-hg-bookmark-string

Called in the Mercurial backend when a bookmark string is generated; the get-revision and get-bookmarks styles must be true.

gen-applied-string

Called in the git (with stgit), and hg (with mq) backends and in quilt support when the applied-string is generated; the use-quilt zstyle must be true for quilt (the mq and stgit backends are active by default).

gen-unapplied-string

Called in the git (with stgit), and hg (with mq) backend and in quilt support when the unapplied-string is generated; the get-unapplied style must be true.

gen-mqguards-string

Called in the hg backend when guards-string is generated; the get-mq style must be true (default).

no-vcs

This hooks is called when no version control system was detected.

post-quilt

Called after the quilt support is done. The following information is passed as arguments to the hook: 1. the quilt-support mode (`addon' or `standalone'); 2. the directory that contains the patch series; 3. the directory that holds quilt's status information (the `.pc' directory) or the string "-nopc-" if that directory wasn't found.

set-branch-format

Called before `branchformat' is set. The only argument to the hook is the format that is configured at this point.

set-hgrev-format

Called before a `hgrevformat' is set. The only argument to the hook is the format that is configured at this point.

set-message

Called each time before a `vcs_info_msg_N_' message is set. It takes two arguments; the first being the `N' in the message variable name, the second is the currently configured formats or actionformats.

If all of this sounds rather confusing, take a look at the Examples section below and also in the Misc/vcs_info-examples file in the Zsh source. They contain some explanatory code.

Examples¶

Don't use vcs_info at all (even though it's in your prompt):

zstyle ':vcs_info:*' enable NONE

Disable the backends for bzr and svk:

zstyle ':vcs_info:*' disable bzr svk

Disable everything but bzr and svk:

zstyle ':vcs_info:*' enable bzr svk

Provide a special formats for git:

zstyle ':vcs_info:git:*' formats       ' GIT, BABY! [%b]'
zstyle ':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]'

All %x expansion in all sorts of formats ("formats", "actionformats", branchformat, you name it) are done using the `zformat' builtin from the `zsh/zutil' module. That means you can do everything with these %x items what zformat supports. In particular, if you want something that is really long to have a fixed width, like a hash in a mercurial branchformat, you can do this: %12.12i. That'll shrink the 40 character hash to its 12 leading characters. The form is actually `%min.maxx'. More is possible. See the section `The zsh/zutil Module' in zshmodules(1) for details.

Use the quicker bzr backend

zstyle ':vcs_info:bzr:*' use-simple true

If you do use use-simple, please report if it does `the-right-thing[tm]'.

Display the revision number in yellow for bzr and svn:

zstyle ':vcs_info:(svn|bzr):*' branchformat '%b%{'${fg[yellow]}'%}:%r'

If you want colors, make sure you enclose the color codes in %{...%} if you want to use the string provided by vcs_info in prompts.

Here is how to print the VCS information as a command (not in a prompt):

alias vcsi='vcs_info command; vcs_info_lastmsg'

This way, you can even define different formats for output via vcs_info_lastmsg in the ':vcs_info:*:command:*' namespace.

Now as promised, some code that uses hooks: say, you'd like to replace the string `svn' by `subversion' in vcs_info's %s formats replacement.

First, we will tell vcs_info to call a function when populating the message variables with the gathered information:

zstyle ':vcs_info:*+set-message:*' hooks svn2subversion

Nothing happens. Which is reasonable, since we didn't define the actual function yet. To see what the hooks subsystem is trying to do, enable the `debug' style:

zstyle ':vcs_info:*+*:*' debug true

That should give you an idea what is going on. Specifically, the function that we are looking for is `+vi-svn2subversion'. Note, the `+vi-' prefix. So, everything is in order, just as documented. When you are done checking out the debugging output, disable it again:

zstyle ':vcs_info:*+*:*' debug false

Now, let's define the function:

function +vi-svn2subversion() {


    [[ ${hook_com[vcs_orig]} == svn ]] && hook_com[vcs]=subversion
}

Simple enough. And it could have even been simpler, if only we had registered our function in a less generic context. If we do it only in the `svn' backend's context, we don't need to test which the active backend is:

zstyle ':vcs_info:svn+set-message:*' hooks svn2subversion

function +vi-svn2subversion() {


    hook_com[vcs]=subversion
}

And finally a little more elaborate example, that uses a hook to create a customised bookmark string for the hg backend.

Again, we start off by registering a function:

zstyle ':vcs_info:hg+gen-hg-bookmark-string:*' hooks hgbookmarks

And then we define the `+vi-hgbookmarks function:

function +vi-hgbookmarks() {


    # The default is to connect all bookmark names by


    # commas. This mixes things up a little.


    # Imagine, there's one type of bookmarks that is


    # special to you. Say, because it's *your* work.


    # Those bookmarks look always like this: "sh/*"


    # (because your initials are sh, for example).


    # This makes the bookmarks string use only those


    # bookmarks. If there's more than one, it


    # concatenates them using commas.


    local s i


    # The bookmarks returned by `hg' are available in


    # the functions positional parameters.


    (( $# == 0 )) && return 0


    for i in "$@"; do


        if [[ $i == sh/* ]]; then


            [[ -n $s ]] && s=$s,


            s=${s}$i


        fi


    done


    # Now, the communication with the code that calls


    # the hook functions is done via the hook_com[]


    # hash. The key, at which the `gen-hg-bookmark-string'


    # hook looks at is `hg-bookmark-string'. So:


    hook_com[hg-bookmark-string]=$s


    # And to signal, that we want to use the sting we


    # just generated, set the special variable `ret' to


    # something other than the default zero:


    ret=1


    return 0
}

Some longer examples and code snippets which might be useful are available in the examples file located at Misc/vcs_info-examples in the Zsh source directory.

This concludes our guided tour through zsh's vcs_info.

Installation¶

You should make sure all the functions from the Functions/Prompts directory of the source distribution are available; they all begin with the string `prompt_' except for the special function`promptinit'. You also need the `colors' function from Functions/Misc. All of these functions may already have been installed on your system; if not, you will need to find them and copy them. The directory should appear as one of the elements of the fpath array (this should already be the case if they were installed), and at least the function promptinit should be autoloaded; it will autoload the rest. Finally, to initialize the use of the system you need to call the promptinit function. The following code in your .zshrc will arrange for this; assume the functions are stored in the directory ~/myfns:

fpath=(~/myfns $fpath)
autoload -U promptinit
promptinit

Theme Selection¶

Use the prompt command to select your preferred theme. This command may be added to your .zshrc following the call to promptinit in order to start zsh with a theme already selected.

prompt [ -c | -l ]

prompt [ -p | -h ] [ theme ... ]

prompt [ -s ] theme [ arg ... ]

Set or examine the prompt theme. With no options and a theme argument, the theme with that name is set as the current theme. The available themes are determined at run time; use the -l option to see a list. The special theme `random' selects at random one of the available themes and sets your prompt to that.

prompt_theme_setup

Each available theme has a setup function which is called by the prompt function to install that theme. This function may define other functions as necessary to maintain the prompt, including functions used to preview the prompt or provide help for its use. You should not normally call a theme's setup function directly.

Widgets¶

These functions all implement user-defined ZLE widgets (see zshzle(1)) which can be bound to keystrokes in interactive shells. To use them, your .zshrc should contain lines of the form

autoload function
zle -N function

followed by an appropriate bindkey command to associate the function with a key sequence. Suggested bindings are described below.

bash-style word functions

If you are looking for functions to implement moving over and editing words in the manner of bash, where only alphanumeric characters are considered word characters, you can use the functions described in the next section. The following is sufficient:

autoload -U select-word-style
select-word-style bash

forward-word-match, backward-word-match

kill-word-match, backward-kill-word-match

transpose-words-match, capitalize-word-match

up-case-word-match, down-case-word-match

select-word-style, match-word-context, match-words-by-style

The eight `-match' functions are drop-in replacements for the builtin widgets without the suffix. By default they behave in a similar way. However, by the use of styles and the function select-word-style, the way words are matched can be altered.

zstyle ':zle:transpose-words' skip-chars 1

zstyle ':zle:*' word-style standard
zstyle ':zle:*' word-chars ''

style ':zle:*kill*' word-style space

zstyle ':zle:*' word-context "*/*" file "[[:space:]]" whitespace
zstyle ':zle:transpose-words:whitespace' word-style shell
zstyle ':zle:transpose-words:filename' word-style normal
zstyle ':zle:transpose-words:filename' word-chars ''

copy-earlier-word

This widget works like a combination of insert-last-word and copy-prev-shell-word. Repeated invocations of the widget retrieve earlier words on the relevant history line. With a numeric argument N, insert the Nth word from the history line; N may be negative to count from the end of the line.

cycle-completion-positions

After inserting an unambiguous string into the command line, the new function based completion system may know about multiple places in this string where characters are missing or differ from at least one of the possible matches. It will then place the cursor on the position it considers to be the most interesting one, i.e. the one where one can disambiguate between as many matches as possible with as little typing as possible.

delete-whole-word-match

This is another function which works like the -match functions described immediately above, i.e. using styles to decide the word boundaries. However, it is not a replacement for any existing function.

zle -N kill-whole-word-match delete-whole-word-match

up-line-or-beginning-search, down-line-or-beginning-search

These widgets are similar to the builtin functions up-line-or-search and down-line-or-search: if in a multiline buffer they move up or down within the buffer, otherwise they search for a history line matching the start of the current line. In this case, however, they search for a line which matches the current line up to the current cursor position, in the manner of history-beginning-search-backward and -forward, rather than the first word on the line.

edit-command-line

Edit the command line using your visual editor, as in ksh.

bindkey -M vicmd v edit-command-line

history-search-end

This function implements the widgets history-beginning-search-backward-end and history-beginning-search-forward-end. These commands work by first calling the corresponding builtin widget (see `History Control' in zshzle(1)) and then moving the cursor to the end of the line. The original cursor position is remembered and restored before calling the builtin widget a second time, so that the same search is repeated to look farther through the history.

zle -N history-beginning-search-backward-end \ 


       history-search-end
zle -N history-beginning-search-forward-end \ 


       history-search-end
bindkey '\e^P' history-beginning-search-backward-end
bindkey '\e^N' history-beginning-search-forward-end

history-beginning-search-menu

This function implements yet another form of history searching. The text before the cursor is used to select lines from the history, as for history-beginning-search-backward except that all matches are shown in a numbered menu. Typing the appropriate digits inserts the full history line. Note that leading zeroes must be typed (they are only shown when necessary for removing ambiguity). The entire history is searched; there is no distinction between forwards and backwards.

zle -N history-beginning-search-menu-space-end \ 


       history-beginning-search-menu

history-pattern-search

The function history-pattern-search implements widgets which prompt for a pattern with which to search the history backwards or forwards. The pattern is in the usual zsh format, however the first character may be ^ to anchor the search to the start of the line, and the last character may be $ to anchor the search to the end of the line. If the search was not anchored to the end of the line the cursor is positioned just after the pattern found.

autoload -U history-pattern-search
zle -N history-pattern-search-backward history-pattern-search
zle -N history-pattern-search-forward history-pattern-search

incarg

Typing the keystrokes for this widget with the cursor placed on or to the left of an integer causes that integer to be incremented by one. With a numeric prefix argument, the number is incremented by the amount of the argument (decremented if the prefix argument is negative). The shell parameter incarg may be set to change the default increment to something other than one.

bindkey '^X+' incarg

incremental-complete-word

This allows incremental completion of a word. After starting this command, a list of completion choices can be shown after every character you type, which you can delete with ^H or DEL. Pressing return accepts the completion so far and returns you to normal editing (that is, the command line is not immediately executed). You can hit TAB to do normal completion, ^G to abort back to the state when you started, and ^D to list the matches.

bindkey '^Xi' incremental-complete-word

insert-composed-char

This function allows you to compose characters that don't appear on the keyboard to be inserted into the command line. The command is followed by two keys corresponding to ASCII characters (there is no prompt). For accented characters, the two keys are a base character followed by a code for the accent, while for other special characters the two characters together form a mnemonic for the character to be inserted. The two-character codes are a subset of those given by RFC 1345 (see for example http://www.faqs.org/rfcs/rfc1345.html).

insert-files

This function allows you type a file pattern, and see the results of the expansion at each step. When you hit return, all expansions are inserted into the command line.

bindkey '^Xf' insert-files

insert-unicode-char

When first executed, the user inputs a set of hexadecimal digits. This is terminated with another call to insert-unicode-char. The digits are then turned into the corresponding Unicode character. For example, if the widget is bound to ^XU, the character sequence `^XU 4 c ^XU' inserts L (Unicode U+004c).

narrow-to-region [ -p pre ] [ -P post ]

[ -S statepm | -R statepm ] [ -n ] [ start end ])

narrow-to-region-invisible

Narrow the editable portion of the buffer to the region between the cursor and the mark, which may be in either order. The region may not be empty.

local state
narrow-to-region -p $'Editing restricted region\n' \ 


  -P '' -S state
zle recursive-edit
narrow-to-region -R state

predict-on

This set of functions implements predictive typing using history search. After predict-on, typing characters causes the editor to look backward in the history for the first line beginning with what you have typed so far. After predict-off, editing returns to normal for the line found. In fact, you often don't even need to use predict-off, because if the line doesn't match something in the history, adding a key performs standard completion, and then inserts itself if no completions were found. However, editing in the middle of a line is liable to confuse prediction; see the toggle style below.

zle -N predict-on
zle -N predict-off
bindkey '^X^Z' predict-on
bindkey '^Z' predict-off

read-from-minibuffer

This is most useful when called as a function from inside a widget, but will work correctly as a widget in its own right. It prompts for a value below the current command line; a value may be input using all of the standard zle operations (and not merely the restricted set available when executing, for example, execute-named-cmd). The value is then returned to the calling function in the parameter $REPLY and the editing buffer restored to its previous state. If the read was aborted by a keyboard break (typically ^G), the function returns status 1 and $REPLY is not set.

replace-string, replace-pattern

replace-string-again, replace-pattern-again

The function replace-string implements three widgets. If defined under the same name as the function, it prompts for two strings; the first (source) string will be replaced by the second everywhere it occurs in the line editing buffer.

print This line contains fan and fond

print This line contains car and cord

send-invisible

This is similar to read-from-minibuffer in that it may be called as a function from a widget or as a widget of its own, and interactively reads input from the keyboard. However, the input being typed is concealed and a string of asterisks (`*') is shown instead. The value is saved in the parameter $INVISIBLE to which a reference is inserted into the editing buffer at the restored cursor position. If the read was aborted by a keyboard break (typically ^G) or another escape from editing such as push-line, $INVISIBLE is set to empty and the original buffer is restored unchanged.

smart-insert-last-word

This function may replace the insert-last-word widget, like so:

zle -N insert-last-word smart-insert-last-word

zle -N insert-last-assignment smart-insert-last-word
zstyle :insert-last-assignment match '[[:alpha:]][][[:alnum:]]#=*'
bindkey '\e=' insert-last-assignment

transpose-lines

Only useful with a multi-line editing buffer; the lines here are lines within the current on-screen buffer, not history lines. The effect is similar to the function of the same name in Emacs.

which-command

This function is a drop-in replacement for the builtin widget which-command. It has enhanced behaviour, in that it correctly detects whether or not the command word needs to be expanded as an alias; if so, it continues tracing the command word from the expanded alias until it reaches the command that will be executed.

Utility Functions¶

These functions are useful in constructing widgets. They should be loaded with `autoload -U function' and called as indicated from user-defined widgets.

split-shell-arguments

This function splits the line currently being edited into shell arguments and whitespace. The result is stored in the array reply. The array contains all the parts of the line in order, starting with any whitespace before the first argument, and finishing with any whitespace after the last argument. Hence (so long as the option KSH_ARRAYS is not set) whitespace is given by odd indices in the array and arguments by even indices. Note that no stripping of quotes is done; joining together all the elements of reply in order is guaranteed to produce the original line.

modify-current-argument expr-using-$ARG

This function provides a simple method of allowing user-defined widgets to modify the command line argument under the cursor (or immediately to the left of the cursor if the cursor is between arguments). The argument should be an expression which when evaluated operates on the shell parameter ARG, which will have been set to the command line argument under the cursor. The expression should be suitably quoted to prevent it being evaluated too early.

modify-current-argument '${(U)ARG}'

modify-current-argument '${(qq)${(Q)ARG}}'

Styles¶

The behavior of several of the above widgets can be controlled by the use of the zstyle mechanism. In particular, widgets that interact with the completion system pass along their context to any completions that they invoke.

break-keys

This style is used by the incremental-complete-word widget. Its value should be a pattern, and all keys matching this pattern will cause the widget to stop incremental completion without the key having any further effect. Like all styles used directly by incremental-complete-word, this style is looked up using the context `:incremental'.

completer

The incremental-complete-word and insert-and-predict widgets set up their top-level context name before calling completion. This allows one to define different sets of completer functions for normal completion and for these widgets. For example, to use completion, approximation and correction for normal completion, completion and correction for incremental completion and only completion for prediction one could use:

zstyle ':completion:*' completer \ 


        _complete _correct _approximate
zstyle ':completion:incremental:*' completer \ 


        _complete _correct
zstyle ':completion:predict:*' completer \ 


        _complete

cursor

The insert-and-predict widget uses this style, in the context `:predict', to decide where to place the cursor after completion has been tried. Values are:

list

When using the incremental-complete-word widget, this style says if the matches should be listed on every key press (if they fit on the screen). Use the context prefix `:completion:incremental'.

match

This style is used by smart-insert-last-word to provide a pattern (using full EXTENDED_GLOB syntax) that matches an interesting word. The context is the name of the widget to which smart-insert-last-word is bound (see above). The default behavior of smart-insert-last-word is equivalent to:

zstyle :insert-last-word match '*[[:alpha:]/\\]*'

zstyle :insert-last-word match '*[[:alpha:][:space:]/\\]*'

zstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\])*'

prompt

The incremental-complete-word widget shows the value of this style in the status line during incremental completion. The string value may contain any of the following substrings in the manner of the PS1 and other prompt parameters:

stop-keys

This style is used by the incremental-complete-word widget. Its value is treated similarly to the one for the break-keys style (and uses the same context: `:incremental'). However, in this case all keys matching the pattern given as its value will stop incremental completion and will then execute their usual function.

toggle

This boolean style is used by predict-on and its related widgets in the context `:predict'. If set to one of the standard `true' values, predictive typing is automatically toggled off in situations where it is unlikely to be useful, such as when editing a multi-line buffer or after moving into the middle of a line and then deleting a character. The default is to leave prediction turned on until an explicit call to predict-off.

verbose

This boolean style is used by predict-on and its related widgets in the context `:predict'. If set to one of the standard `true' values, these widgets display a message below the prompt when the predictive state is toggled. This is most useful in combination with the toggle style. The default does not display these messages.

widget

This style is similar to the command style: For widget functions that use zle to call other widgets, this style can sometimes be used to override the widget which is called. The context for this style is the name of the calling widget (not the name of the calling function, because one function may be bound to multiple widget names).

zstyle :copy-earlier-word widget smart-insert-last-word

Descriptions¶

colors

This function initializes several associative arrays to map color names to (and from) the ANSI standard eight-color terminal codes. These are used by the prompt theme system (see above). You seldom should need to run colors more than once.

fned name

Same as zed -f. This function does not appear in the zsh distribution, but can be created by linking zed to the name fned in some directory in your fpath.

is-at-least needed [ present ]

Perform a greater-than-or-equal-to comparison of two strings having the format of a zsh version number; that is, a string of numbers and text with segments separated by dots or dashes. If the present string is not provided, $ZSH_VERSION is used. Segments are paired left-to-right in the two strings with leading non-number parts ignored. If one string has fewer segments than the other, the missing segments are considered zero.

is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS
is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS
is-at-least 2.6-17 || print "You can't use is-at-least here."

nslookup [ arg ... ]

This wrapper function for the nslookup command requires the zsh/zpty module (see zshmodules(1)). It behaves exactly like the standard nslookup except that it provides customizable prompts (including a right-side prompt) and completion of nslookup commands, host names, etc. (if you use the function-based completion system). Completion styles may be set with the context prefix `:completion:nslookup'.

regexp-replace var regexp replace

Use regular expressions to perform a global search and replace operation on a variable. If the option RE_MATCH_PCRE is not set, POSIX extended regular expressions are used, else Perl-compatible regular expressions (this requires the shell to be linked against the pcre library).

run-help cmd

This function is designed to be invoked by the run-help ZLE widget, in place of the default alias. See `Accessing On-Line Help' above for setup instructions.

run-help-ssh() {


    emulate -LR zsh


    local -a args


    # Delete the "-l username" option


    zparseopts -D -E -a args l:


    # Delete other options, leaving: host command


    args=(${@:#-*})


    if [[ ${#args} -lt 2 ]]; then


        man ssh


    else


        run-help $args[2]


    fi
}

tetris

Zsh was once accused of not being as complete as Emacs, because it lacked a Tetris game. This function was written to refute this vicious slander.

autoload -U tetris
zle -N tetris
bindkey keys tetris

zargs [ option ... -- ] [ input ... ] [ -- command [ arg ... ] ]

This function has a similar purpose to GNU xargs. Instead of reading lines of arguments from the standard input, it takes them from the command line. This is useful because zsh, especially with recursive glob operators, often can construct a command line for a shell function that is longer than can be accepted by an external command.

autoload -U zargs
zargs -- **/*(.) -- ls -l

zargs -e.. -- **/*(.) .. ls -l

zed [ -f ] name

zed -b

This function uses the ZLE editor to edit a file or function.

zcp [ -finqQvwW ] srcpat dest

zln [ -finqQsvwW ] srcpat dest

Same as zmv -C and zmv -L, respectively. These functions do not appear in the zsh distribution, but can be created by linking zmv to the names zcp and zln in some directory in your fpath.

zkbd

See `Keyboard Definition' above.

zmv [ -finqQsvwW ] [ -C | -L | -M | -p program ] [ -o optstring ] srcpat dest

Move (usually, rename) files matching the pattern srcpat to corresponding files having names of the form given by dest, where srcpat contains parentheses surrounding patterns which will be replaced in turn by $1, $2, ... in dest. For example,

zmv '(*).lis' '$1.txt'

zmv -v '(* *)' '${1// /_}'

zrecompile

See `Recompiling Functions' above.

zstyle+ context style value [ + subcontext style value ... ]

This makes defining styles a bit simpler by using a single `+' as a special token that allows you to append a context name to the previously used context name. Like this:

zstyle+ ':foo:bar' style1 value1 \ 


      + ':baz'     style2 value2 \ 


      + ':frob'    style3 value3

Styles¶

insert-tab

The zed function sets this style in context `:completion:zed:*' to turn off completion when TAB is typed at the beginning of a line. You may override this by setting your own value for this context and style.

pager

The nslookup function looks up this style in the context `:nslookup' to determine the program used to display output that does not fit on a single screen.

prompt

rprompt

The nslookup function looks up this style in the context `:nslookup' to set the prompt and the right-side prompt, respectively. The usual expansions for the PS1 and RPS1 parameters may be used (see EXPANSION OF PROMPT SEQUENCES in zshmisc(1)).