man pages section 1: User Commands

Exit Print View

Updated: July 2014

zshcontrib (1)


zshcontrib - user contributions to zsh


Please see following description for synopsis


User Commands                                       ZSHCONTRIB(1)

     zshcontrib - user contributions to zsh

     The  Zsh source distribution includes a number of items con-
     tributed by the user community.  These are not inherently  a
     part  of  the  shell, and some may not be available in every
     zsh installation.  The most significant of these  are  docu-
     mented  here.   For documentation on other contributed items
     such as shell functions, look for comments in  the  function
     source files.

  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 com-
     mand 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

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

     To create your own help files with helpfiles, choose or cre-
     ate 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.5/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:

zsh 5.0.5          Last change: January 5, 2014                 1

User Commands                                       ZSHCONTRIB(1)

          unalias run-help
          autoload run-help

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

     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  direc-

  Recompiling Functions
     If  you  frequently edit your zsh functions, or periodically
     update your zsh installation to track  the  latest  develop-
     ments,  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   Func-
     tions/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

          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) other-
          wise.   The  -q  option  quiets  the chatty output that
          describes what zrecompile is doing.

zsh 5.0.5          Last change: January 5, 2014                 2

User Commands                                       ZSHCONTRIB(1)

          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

          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 com-
          piled  file  will be marked for reading instead of map-
          ping. The same is done for ~/.zcompdump  and  ~/.zcomp-
          dump.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

          Without the -p option, zrecompile does not create func-
          tion 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  cre-
     ating  function  digests  for  all  functions in your fpath,
     assuming that you have write permission to the directories:

          for ((i=1; i <= $#fpath; ++i)); do
            if [[ $dir == (.|..) || $dir == (.|..)/* ]]; then
            if [[ -w $dir:h && -n $files ]]; then
              if ( cd $dir:h &&
                   zrecompile -p -U -z $zwc $files ); then

     The -U and -z options are appropriate for functions  in  the
     default  zsh installation fpath; you may need to use differ-
     ent options for your personal function directories.

zsh 5.0.5          Last change: January 5, 2014                 3

User Commands                                       ZSHCONTRIB(1)

     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 configura-

     Run  zkbd  either  as  an autoloaded function, or as a shell

          zsh -f ~/zsh-5.0.5/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 ter-
     minal; zkbd warns you if it finds anything out of the  ordi-
     nary, 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 direc-
     tory.  The name of the file is composed from the TERM,  VEN-
     DOR 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

zsh 5.0.5          Last change: January 5, 2014                 4

User Commands                                       ZSHCONTRIB(1)

     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.5/Util/reporter >

     You  should  check  the  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  func-
     tion 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:

          all  Output everything listed below.
               Output alias definitions.
               Output ZLE key maps and bindings.
               Output old-style compctl commands.  New completion
               is covered by functions and zstyles.
               Output autoloads and function definitions.

zsh 5.0.5          Last change: January 5, 2014                 5

User Commands                                       ZSHCONTRIB(1)

               Output limit commands.
               Output setopt commands.
               Same as zstyles.
               Output shell parameter  assignments,  plus  export
               commands for any environment variables.
               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.

  Manipulating Hook Functions
     add-zsh-hook [-dD] hook function
          Several   functions   are  special  to  the  shell,  as
          described in the section SPECIAL  FUNCTIONS,  see  zsh-
          misc(1),  in  that  they are automatic called at a spe-
          cific point during shell execution.  Each has an  asso-
          ciated  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

          hook is one of chpwd, periodic, precmd, preexec, zshad-
          dhistory, 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.

          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.

zsh 5.0.5          Last change: January 5, 2014                 6

User Commands                                       ZSHCONTRIB(1)

     The function cdr allows you to change the working  directory
     to a previous working directory from a list maintained auto-
     matically.  It is similar in concept to the directory  stack
     controlled by the pushd, popd and dirs builtins, but is more
     configurable, and as it stores all entries in  files  it  is
     maintained across sessions and (by default) between terminal
     emulators in the  current  session.   (The  pushd  directory
     stack  is  not  actually  modified or used by cdr unless you
     configure it to do so as described in the configuration sec-
     tion below.)

     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.

     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 mul-
     tiple 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 direc-
     tories 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

zsh 5.0.5          Last change: January 5, 2014                 7

User Commands                                       ZSHCONTRIB(1)

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

     The behaviour of  cdr  may  be  modified  by  the  following

     -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  con-
          tained a newline).  This is used by the completion sys-

     -r   sets the variable reply to the current set of  directo-
          ries.   Nothing  is  printed  and  the directory is not

     -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  avail-
          able.   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  is  by  means  of  the  styles mechanism that
     should be familiar from completion; if not, see the descrip-
     tion  of  the zstyle command in see zshmodules(1).  The con-
     text 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 prac-
     tice the style name is specific enough that a context of '*'
     should be fine.

     An  exception  is  recent-dirs-insert,  which is used exclu-
     sively by the completion system and so has the usual comple-
     tion  system  context  (':completion:*' if nothing more spe-
     cific is needed), though again '*' should be fine  in  prac-

          If   true,  and  the  command  is  expecting  a  recent

zsh 5.0.5          Last change: January 5, 2014                 8

User Commands                                       ZSHCONTRIB(1)

          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.

          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

          The value of this style may be an array.  In this case,
          the first file in the list will always be used for sav-
          ing   directories   while  any  other  files  are  left
          untouched.  When reading the recent directory list,  if
          there  are  fewer than the maximum number of entries in
          the first file, the contents  of  later  files  in  the
          array will be appended with duplicates removed from the
          list shown.  The contents of  the  two  files  are  not
          sorted together, i.e. all the entries in the first file
          are shown first.  The special value + can appear in the
          list  to  indicate  the  default file should be read at
          that point.  This allows effects like the following:

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

          Recent  directories  are  read  from  a  file  numbered
          according  to  the terminal.  If there are insufficient
          entries the list is supplemented from the default file.

          It  is  possible to use zstyle -e to make the directory
          configurable at run time:

               zstyle -e ':chpwd:*' recent-dirs-file pick-recent-dirs-file
               pick-recent-dirs-file() {
                 if [[ $PWD = ~/text/writing(|/*) ]]; then

          In  this  example,  if   the   current   directory   is
          ~/text/writing or a directory under it, then use a spe-
          cial file for saving recent directories, else  use  the

zsh 5.0.5          Last change: January 5, 2014                 9

User Commands                                       ZSHCONTRIB(1)

          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 correspond-
          ing  index,  but makes the history clearer and the line
          easier to edit.  With this setting, if part of an argu-
          ment  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.

          If the value of the style is always, then  only  recent
          directories will be completed; in that case, use the cd
          command when you want to complete other directories.

          If the value is fallback, recent  directories  will  be
          tried  first,  then normal directory completion is per-
          formed if recent directory completion failed to find  a

          Finally, if the value is both then both sets of comple-
          tions are presented; the usual  tag  mechanism  can  be
          used  to  distinguish  results, with recent directories
          tagged as recent-dirs.  Note that the  recent  directo-
          ries  inserted  are  abbreviated  with  directory names
          where appropriate.

          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  direc-
          tory,  which  isn't  offered,  so the highest number of
          directories you will be offered is one  less  than  the

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

               Prune  parents  (more  accurately, ancestors) from
               the recent list.  If  present,  changing  directly
               down  by any number of directories causes the cur-
               rent directory to be  overwritten.   For  example,
               changing  from  ~pws to ~pws/some/other/dir causes
               ~pws not to be left on the recent directory stack.
               This  only applies to direct changes to descendant
               directories; earlier directories on the  list  are
               not    pruned.    For   example,   changing   from
               ~pws/yet/another to ~pws/some/other/dir  does  not

zsh 5.0.5          Last change: January 5, 2014                10

User Commands                                       ZSHCONTRIB(1)

               cause ~pws to be pruned.

               Gives  a  zsh  pattern for directories that should
               not be added to the recent list  (if  not  already
               there).   This element can be repeated to add dif-
               ferent patterns.  For example, 'pattern:/tmp(|/*)'
               stops  /tmp  or  its descendants from being added.
               The EXTENDED_GLOB option is always turned  on  for
               these patterns.

          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

  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 direc-
     tory  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 lock-
     ing  is applied: the list is updated immediately on interac-
     tive 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 insti-
     tuted 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.

zsh 5.0.5          Last change: January 5, 2014                11

User Commands                                       ZSHCONTRIB(1)

     In a lot of cases, it  is  nice  to  automatically  retrieve
     information  from  version  control  systems (VCSs), such as
     subversion, CVS or git, to be able  to  provide  it  to  the
     user;  possibly  in  the  user's  prompt.  So  that  you can
     instantly tell which branch you are currently on, for  exam-

     In order to do that, you may use the vcs_info function.

     The  following  VCSs  are supported, showing the abbreviated
     name by which they are referred to within the system:
     Bazaar (bzr)

     Codeville (cdv)

     Concurrent Versioning System (cvs)

     Darcs (darcs)

     Fossil (fossil)

     Git (git)

     GNU arch (tla)

     Mercurial (hg)

     Monotone (mtn)

     Perforce (p4)

     Subversion (svn)

     SVK (svk)

     There is also support for the patch management system  quilt
     (  See Quilt Sup-
     port below for details.

     To load vcs_info:

          autoload -Uz vcs_info

     It can be used in any existing prompt, because it  does  not
     require any specific $psvar entries to be available.

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

zsh 5.0.5          Last change: January 5, 2014                12

User Commands                                       ZSHCONTRIB(1)

          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

          % vcs_info_printsys
          ## list of supported version control backends:
          ## disabled systems are prefixed by a hash sign (#)
          ## 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:*'.

     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

zsh 5.0.5          Last change: January 5, 2014                13

User Commands                                       ZSHCONTRIB(1)

          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.

     The vcs_info feature can be configured via zstyle.

     First, the context in which we are working:

          is one of: git, git-svn, git-p4, hg, hg-git,  hg-hgsub-
          version, 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.)

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

          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

     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:
          the one used if none is specified
          used by vcs_info_lastmsg to lookup its styles

zsh 5.0.5          Last change: January 5, 2014                14

User Commands                                       ZSHCONTRIB(1)

     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.

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

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

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

          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.

          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 revi-
          sion  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.

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

          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

zsh 5.0.5          Last change: January 5, 2014                15

User Commands                                       ZSHCONTRIB(1)

          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.

          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.

          Say, ~/.zsh is a directory under  version  control,  in
          which you do not want vcs_info to be active, do:
               zstyle ':vcs_info:*' disable-patterns "$HOME/.zsh(|/*)"

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

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

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

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

          If enabled, this style causes  the  %c  and  %u  format
          escapes  to  show when the working directory has uncom-
          mitted 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).

          For this style to be evaluated with the hg backend, the
          get-revision style needs to be set and  the  use-simple
          style needs to be unset. The latter is the default; the
          former is not.

          Note, the actions taken if this style  is  enabled  are
          potentially  expensive (read: they may be slow, depend-
          ing on how big the current repository is).   Therefore,
          it is disabled by default.

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

zsh 5.0.5          Last change: January 5, 2014                16

User Commands                                       ZSHCONTRIB(1)

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

          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.

          If  the  value  of  this  style  is empty (which is the
          default), the used binary name is the name of the back-
          end in use (e.g. svn is used in an svn repository).

          The  repo-root-name  part  in the context is always the
          default -all- when this style is looked up.

          For example, this style can be  used  to  use  binaries
          from  non-default installation directories. Assume, git
          is installed in /usr/bin but your sysadmin installed  a
          newer  version  in  /usr/bin/local. Instead of changing
          the order of your $PATH parameter, you can do this:
               zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git

          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 describ-
          ing 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.

          If there are two different ways of  gathering  informa-
          tion,  you  can  select the simpler one by setting this
          style to true; the default is to use the  not-that-sim-
          ple  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.


zsh 5.0.5          Last change: January 5, 2014                17

User Commands                                       ZSHCONTRIB(1)

          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  infor-
          mation 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.

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

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

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

          Enable debugging output  to  track  possible  problems.
          Currently  this  style is only used by vcs_info's 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:

          " (%s)-[%b]%u%c-"
          " (%s)-[%b|%a]%u%c-"
          "%b:%r" (for bzr, svn, svk and hg)
          (empty list)
          (empty list)

zsh 5.0.5          Last change: January 5, 2014                18

User Commands                                       ZSHCONTRIB(1)

          (string: "S")
          (string: "U")
          (empty string)
          (empty list)
          empty - use $QUILT_PATCHES

     In  normal  formats and actionformats the following replace-
     ments 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
     %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

zsh 5.0.5          Last change: January 5, 2014                19

User Commands                                       ZSHCONTRIB(1)

          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

     %p   The   name    of    the    top-most    applied    patch
     %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.

     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 incon-
     venience, 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.

zsh 5.0.5          Last change: January 5, 2014                20

User Commands                                       ZSHCONTRIB(1)

     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 config-
     urable 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 gath-
     ered  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 sys-
     tems 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 pro-
     duced string is available as a simple format replacement (%Q
     to  be precise), which can be used in formats and actionfor-
     mats; 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 some-
     thing like `svn' or `cvs') will be set  to  `-quilt-'.  This
     has  implications on the used style context where this iden-
     tifier 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 compati-
     bility with `addon' mode.

zsh 5.0.5          Last change: January 5, 2014                21

User Commands                                       ZSHCONTRIB(1)

     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

     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-con-
          text field of the style context.

          Statically registers a number of functions to  a  given

zsh 5.0.5          Last change: January 5, 2014                22

User Commands                                       ZSHCONTRIB(1)

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

          Remove hook-functions from a given hook. The hook needs
          to be given as the first non-option argument; what fol-
          lows 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.  Oth-
          erwise  only  the last occurance is removed (if a func-
          tion 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.

          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.

          Initializes vcs_info's internal list of available back-
          ends. 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

zsh 5.0.5          Last change: January 5, 2014                23

User Commands                                       ZSHCONTRIB(1)

     and through that, change the system's behaviour.

     For configuration, hooks change the style context:

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

          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  func-
     tion  names  are  prepended by a `+vi-', so the actual func-
     tions called for the `foo' hook are `+vi-bar' and `+vi-baz'.

     If  you  would like to register a function to a hook regard-
     less   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 stati-
     cally registered ones (the ones added by  vcs_info_hookadd).

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

              # do something with ${user_data[myval]}

     There are a number of variables that  are  special  in  hook

     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 docu-
          mentation below for details.


zsh 5.0.5          Last change: January 5, 2014                24

User Commands                                       ZSHCONTRIB(1)

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

          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:

          Called  after  starting  vcs_info but before the VCS in
          this directory is determined. It can be used to deacti-
          vate 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.

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

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

          This hook gets the names  of  the  Mercurial  bookmarks
          that vcs_info collected from `hg'.

          When   setting   ret   to   non-zero,   the  string  in
          ${hook_com[hg-bookmark-string]} will be used in the  %m
          escape  in formats and actionformats and will be avail-
          abe  in  the  global  backend_misc  array  as   ${back-

          Called  in the git (with stgit), and hg (with mq) back-
          ends 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).

          This hook gets the names of all applied  patches  which
          vcs_info  collected so far in the opposite order, which
          means that the first argument is the top-most patch and
          so forth.

          When   setting   ret   to   non-zero,   the  string  in
          ${hook_com[applied-string]} will  be  used  in  the  %m

zsh 5.0.5          Last change: January 5, 2014                25

User Commands                                       ZSHCONTRIB(1)

          escape  in formats and actionformats; it will be avail-
          able  in  the  global  backend_misc  array  as   $back-
          end_misc[patches]};  and  it will be available as %p in
          the patch-format and nopatch-format styles.

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

          This hook gets the names of all unapplied patches which
          vcs_info  collected so far in the opposite order, which
          mean that the first argument is the patch  next-in-line
          to be applied and so forth.

          When   setting   ret   to   non-zero,   the  string  in
          ${hook_com[unapplied-string]} will be available  as  %u
          in the patch-format and nopatch-format styles.

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

          This hook gets the names of any active mq guards.

          When  setting  ret   to   non-zero,   the   string   in
          ${hook_com[guards-string]}  will  be  used  in  the  %g
          escape in the patch-format and nopatch-format styles.

          This hooks is called when no version control system was

          The `hook_com' parameter is not used.

          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 direc-
          tory  that  holds quilt's status information (the `.pc'
          directory) or the string  "-nopc-"  if  that  directory
          wasn't found.

          The `hook_com' parameter is not used.

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

zsh 5.0.5          Last change: January 5, 2014                26

User Commands                                       ZSHCONTRIB(1)

          The  `hook_com' keys considered are `branch' and `revi-
          sion'.  They are set to the values figured out  so  far
          by  vcs_info  and any change will be used directly when
          the actual replacement is done.

          If  ret   is   set   to   non-zero,   the   string   in
          ${hook_com[branch-replace]}  will  be used unchanged as
          the `%b' replacement in the variables set by  vcs_info.

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

          The  `hook_com'  keys considered are `hash' and `local-
          rev'.  They are set to the values figured out so far by
          vcs_info  and any change will be used directly when the
          actual replacement is done.

          If  ret   is   set   to   non-zero,   the   string   in
          ${hook_com[rev-replace]}  will be used unchanged as the
          `%i' replacement in the variables set by vcs_info.

          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  cur-
          rently configured formats or actionformats.

          There  are  a  number of `hook_com' keys, that are used
          here: `action', `branch',  `base',  `base-name',  `sub-
          dir',  `staged',  `unstaged', `revision', `misc', `vcs'
          and one `miscN' entry for  each  backend-specific  data
          field  (N starting at zero). They are set to the values
          figured out so far by vcs_info and any change  will  be
          used directly when the actual replacement is done.

          Since  this  hook is triggered multiple times (once for
          each configured formats or actionformats), each of  the
          `hook_com'  keys  mentioned above (except for the miscN
          entries) has an `_orig' counterpart,  so  even  if  you
          changed  a  value  to your liking you can still get the
          original value in the next run.  Changing  the  `_orig'
          values is probably not a good idea.

          If   ret   is   set   to   non-zero,   the   string  in
          ${hook_com[message]} will be used unchanged as the mes-
          sage by vcs_info.

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

zsh 5.0.5          Last change: January 5, 2014                27

User Commands                                       ZSHCONTRIB(1)


     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  mercu-
     rial  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

     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:*' names-

     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.

zsh 5.0.5          Last change: January 5, 2014                28

User Commands                                       ZSHCONTRIB(1)

     First, we will tell vcs_info to call a function  when  popu-
     lating 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-svn2subver-
     sion'.  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() {

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

     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

zsh 5.0.5          Last change: January 5, 2014                29

User Commands                                       ZSHCONTRIB(1)

              # 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,
              # 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:
              # 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:
              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.

     You should make  sure  all  the  functions  from  the  Func-
     tions/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  func-
     tions  may  already  have  been installed on your system; if
     not, you will need to find them and copy them.   The  direc-
     tory 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

  Theme Selection
     Use the prompt command to select your preferred theme.  This
     command may be added to your .zshrc following  the  call  to

zsh 5.0.5          Last change: January 5, 2014                30

User Commands                                       ZSHCONTRIB(1)

     promptinit  in  order  to  start  zsh  with  a theme already

     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.

          In  some cases the theme may be modified by one or more
          arguments, which should be given after the theme  name.
          See  the  help for each theme for descriptions of these

          Options are:

          -c   Show the currently selected theme and its  parame-
               ters, if any.
          -l   List all available prompt themes.
          -p   Preview the theme named by theme, or all themes if
               no theme is given.
          -h   Show help for the theme named by theme, or for the
               prompt function if no theme is given.
          -s   Set theme as the current theme and save state.

          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

     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.

zsh 5.0.5          Last change: January 5, 2014                31

User Commands                                       ZSHCONTRIB(1)

     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  char-
          acters, 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.

          The simplest way of configuring the functions is to use
          select-word-style, which can either be called as a nor-
          mal function with the appropriate argument, or  invoked
          as a user-defined widget that will prompt for the first
          character of the word style to be used.  The first time
          it is invoked, the eight -match functions will automat-
          ically replace the builtin versions,  so  they  do  not
          need to be loaded explicitly.

          The  word  styles  available  are as follows.  Only the
          first character is examined.

          bash Word characters are alphanumeric characters  only.

               As in normal shell operation:  word characters are
               alphanumeric  characters   plus   any   characters
               present  in  the  string  given  by  the parameter

               Words are complete shell command arguments, possi-
               bly  including  complete  quoted  strings,  or any
               tokens special to the shell.

               Words are  any  set  of  characters  delimited  by

               Restore  the default settings; this is usually the

zsh 5.0.5          Last change: January 5, 2014                32

User Commands                                       ZSHCONTRIB(1)

               same as `normal'.

          All but `default' can be input as an upper case charac-
          ter,  which has the same effect but with subword match-
          ing turned on.  In this case,  words  with  upper  case
          characters  are treated specially: each separate run of
          upper case characters, or an upper case character  fol-
          lowed  by any number of other characters, is considered
          a word.  The style subword-range can supply an alterna-
          tive  character  range  to the default `[:upper:]'; the
          value of the style is treated  as  the  contents  of  a
          `[...]'  pattern  (note  that the outer brackets should
          not be supplied, only those surrounding named  ranges).

          More  control can be obtained using the zstyle command,
          as described in zshmodules(1).  Each style is looked up
          in  the context :zle:widget where widget is the name of
          the user-defined widget, not the name of  the  function
          implementing it, so in the case of the definitions sup-
          plied by select-word-style the appropriate contexts are
          :zle:forward-word,    and    so   on.    The   function
          select-word-style itself always defines styles for  the
          context  `:zle:*'  which can be overridden by more spe-
          cific (longer) patterns as well as explicit contexts.

          The style word-style specifies the rules to use.   This
          may have the following values.

               Use  the  standard shell rules, i.e. alphanumerics
               and $WORDCHARS, unless overridden  by  the  styles
               word-chars or word-class.

               Similar  to normal, but only the specified charac-
               ters, and not also alphanumerics,  are  considered
               word characters.

               The  negation  of specified.  The given characters
               are those which will not be considered part  of  a

               Words  are  obtained  by using the syntactic rules
               for generating shell command arguments.  In  addi-
               tion, special tokens which are never command argu-
               ments such as `()' are also treated as words.

               Words are whitespace-delimited strings of  charac-

zsh 5.0.5          Last change: January 5, 2014                33

User Commands                                       ZSHCONTRIB(1)

          The  first three of those rules usually use $WORDCHARS,
          but the value in the parameter can be overridden by the
          style  word-chars,  which works in exactly the same way
          as $WORDCHARS.  In addition, the style word-class  uses
          character  class  syntax  to group characters and takes
          precedence  over  word-chars  if  both  are  set.   The
          word-class  style  does  not  include  the  surrounding
          brackets  of  the   character   class;   for   example,
          `-:[:alnum:]'  is  a  valid  word-class  to include all
          alphanumerics plus the  characters  `-'  and  `:'.   Be
          careful including `]', `^' and `-' as these are special
          inside character classes.

          word-style may also have  `-subword'  appended  to  its
          value  to turn on subword matching, as described above.

          The  style  skip-chars  is  mostly  useful  for  trans-
          pose-words  and  similar functions.  If set, it gives a
          count of characters starting  at  the  cursor  position
          which  will  not be considered part of the word and are
          treated as space, regardless of what they actually are.
          For example, if

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

          has  been set, and transpose-words-match is called with
          the cursor on the X of fooXbar,  where  X  can  be  any
          character, then the resulting expression is barXfoo.

          Finer  grained  control  can be obtained by setting the
          style word-context to an array  of  pairs  of  entries.
          Each  pair  of entries consists of a pattern and a sub-
          context.  The  shell  argument  the  cursor  is  on  is
          matched against each pattern in turn until one matches;
          if it does, the context is extended by a colon and  the
          corresponding  subcontext.   Note that the test is made
          against the original word on the line, with  no  strip-
          ping  of  quotes.   Special  handling  is  done between
          words: the current context is examined and if  it  con-
          tains  the  string  back, the word before the cursor is
          considered, else the word after cursor  is  considered.
          Some examples are given below.

          The  style  skip-whitespace-first is only used with the
          forward-word widget.  If it is set to true,  then  for-
          ward-word  skips  any  non-word-characters, followed by
          any non-word-characters: this is similar to the  behav-
          iour  of  other  word-orientated widgets, and also that
          used by other editors,  however  it  differs  from  the
          standard  zsh  behaviour.  When using select-word-style
          the widget is set in the context :zle:* to true if  the
          word  style  is  bash  and  false otherwise.  It may be

zsh 5.0.5          Last change: January 5, 2014                34

User Commands                                       ZSHCONTRIB(1)

          overridden by setting it in the more  specific  context

          Here  are  some examples of use of the styles, actually
          taken    from    the    simplified     interface     in

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

          Implements  bash-style  word  handling for all widgets,
          i.e. only alphanumerics are word characters; equivalent
          to  setting the parameter WORDCHARS empty for the given

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

          Uses space-delimited words for widgets  with  the  word
          `kill'  in  the name.  Neither of the styles word-chars
          nor word-class is used in this case.

          Here are some examples of use of the word-context style
          to extend the context.

               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 ''

          This  provides  two  different  ways  of  using  trans-
          pose-words depending on whether the cursor is on white-
          space  between  words  or  on a filename, here any word
          containing a /.  On whitespace, complete  arguments  as
          defined by standard shell rules will be transposed.  In
          a filename,  only  alphanumerics  will  be  transposed.
          Elsewhere,  words  will be transposed using the default
          style for :zle:transpose-words.

          The word matching and all the handling of  zstyle  set-
          tings   is   actually   implemented   by  the  function
          match-words-by-style.  This can be used to  create  new
          user-defined  widgets.  The calling function should set
          the local parameter curcontext to  :zle:widget,  create
          the    local    parameter    matched_words   and   call
          match-words-by-style with  no  arguments.   On  return,
          matched_words  will  be  set  to an array with the ele-
          ments: (1) the start of the line (2)  the  word  before
          the  cursor  (3)  any  non-word characters between that
          word and the cursor (4) any non-word character  at  the
          cursor  position plus any remaining non-word characters
          before the next word, including all  characters  speci-
          fied  by  the  skip-chars  style,  (5)  the  word at or

zsh 5.0.5          Last change: January 5, 2014                35

User Commands                                       ZSHCONTRIB(1)

          following the cursor (6) any non-word  characters  fol-
          lowing that word (7) the remainder of the line.  Any of
          the elements may be an empty string; the calling  func-
          tion should test for this to decide whether it can per-
          form its function.

          It is  possible  to  pass  options  with  arguments  to
          match-words-by-style  to  override  the  use of styles.
          The options are:
          -w   word-style
          -s   skip-chars
          -c   word-class
          -C   word-chars
          -r   subword-range

          For example, match-words-by-style -w shell -c 0 may  be
          used to extract the command argument around the cursor.

          The word-context style is implemented by  the  function
          match-word-context.  This should not usually need to be
          called directly.

          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.

          If  insert-last-word has been used to retrieve the last
          word on a previous history line,  repeated  invocations
          will replace that word with earlier words from the same

          Otherwise, the widget applies to words on the line cur-
          rently  being  edited.   The widget style can be set to
          the name of another widget that  should  be  called  to
          retrieve words.  This widget must accept the same three
          arguments as insert-last-word.

          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.

zsh 5.0.5          Last change: January 5, 2014                36

User Commands                                       ZSHCONTRIB(1)

          This widget allows the cursor to be easily moved to the
          other interesting spots.  It can be invoked  repeatedly
          to  cycle between all positions reported by the comple-
          tion system.

          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.

          The  basic  behaviour  is to delete the word around the
          cursor.  There is no numeric prefix handling; only  the
          single  word  around  the cursor is considered.  If the
          widget contains the string kill, the removed text  will
          be  placed  in  the cutbuffer for future yanking.  This
          can be obtained by  defining  kill-whole-word-match  as

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

          and then binding the widget kill-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 match-
          ing  the start of the current line.  In this case, how-
          ever, 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  the  command line using your visual editor, as in

               bindkey -M vicmd v edit-command-line

          This function  implements  the  widgets  history-begin-
          ning-search-backward-end       and       history-begin-
          ning-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 wid-
          get  a second time, so that the same search is repeated
          to look farther through the history.

zsh 5.0.5          Last change: January 5, 2014                37

User Commands                                       ZSHCONTRIB(1)

          Although you autoload only one function,  the  commands
          to  use it are slightly different because it implements
          two widgets.

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

          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-begin-
          ning-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  neces-
          sary  for  removing  ambiguity).  The entire history is
          searched; there is no distinction between forwards  and

          With  a  prefix argument, the search is not anchored to
          the start of the line; the string typed by the use  may
          appear anywhere in the line in the history.

          If  the widget name contains `-end' the cursor is moved
          to the end of the line inserted.  If  the  widget  name
          contains  `-space'  any  space  in  the  text  typed is
          treated as a wildcard and can match anything  (hence  a
          leading  space  is  equivalent to giving a prefix argu-
          ment).  Both forms can be combined, for example:

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

          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.

          The commands to create bindable widgets are similar  to
          those in the example immediately above:

zsh 5.0.5          Last change: January 5, 2014                38

User Commands                                       ZSHCONTRIB(1)

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

          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 pre-
          fix 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

               bindkey '^X+' incarg

          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 exe-
          cuted).  You can hit TAB to do normal completion, ^G to
          abort  back  to  the  state when you started, and ^D to
          list the matches.

          This works only with the new function based  completion

               bindkey '^Xi' incremental-complete-word

          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 cor-
          responding to ASCII characters (there  is  no  prompt).
          For  accented characters, the two keys are a base char-
          acter 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

          The  function  may  optionally be followed by up to two
          characters which replace one or both of the  characters
          read  from  the  keyboard;  if both characters are sup-
          plied, no input  is  read.   For  example,  insert-com-
          posed-char  a: can be used within a widget to insert an
          a with umlaut into the  command  line.   This  has  the
          advantages  over  use of a literal character that it is

zsh 5.0.5          Last change: January 5, 2014                39

User Commands                                       ZSHCONTRIB(1)

          more portable.

          For best results zsh should have been built  with  sup-
          port   for   multibyte   characters   (configured  with
          --enable-multibyte); however, the  function  works  for
          the  limited  range  of  characters  available  in sin-
          gle-byte character sets such as ISO-8859-1.

          The character is converted into the  local  representa-
          tion  and  inserted into the command line at the cursor
          position.  (The conversion is done  within  the  shell,
          using  whatever  facilities  the  C  library provides.)
          With a numeric argument, the character and its code are
          previewed in the status line

          The  function  may  be run outside zle in which case it
          prints the character (together with a newline) to stan-
          dard output.  Input is still read from keystrokes.

          See  insert-unicode-char  for  an  alternative  way  of
          inserting Unicode characters  using  their  hexadecimal
          character number.

          The  set  of accented characters is reasonably complete
          up to Unicode character  U+0180,  the  set  of  special
          characters  less so.  However, it is very sporadic from
          that point.  Adding new characters  is  easy,  however;
          see  the  function  define-composed-chars.  Please send
          any additions to

          The codes for the second character when used to  accent
          the  first are as follows.  Note that not every charac-
          ter can take every accent.
          !    Grave.
          '    Acute.
          >    Circumflex.
          ?    Tilde.  (This is not ~ as RFC 1345 does not assume
               that character is present on the keyboard.)
          -    Macron.   (A  horizontal bar over the base charac-
          (    Breve.  (A shallow dish shape over the base  char-
          .    Dot  above the base character, or in the case of i
               no dot, or in the case of L and l a centered  dot.
          :    Diaeresis (Umlaut).
          c    Cedilla.
          _    Underline,  however  there are currently no under-
               lined characters.
          /    Stroke through the base character.
          "    Double acute (only supported on a few letters).
          ;    Ogonek.  (A little forward facing hook at the bot-
               tom right of the character.)

zsh 5.0.5          Last change: January 5, 2014                40

User Commands                                       ZSHCONTRIB(1)

          <    Caron.  (A little v over the letter.)
          0    Circle over the base character.
          2    Hook over the base character.
          9    Horn over the base character.

          The  most  common characters from the Arabic, Cyrillic,
          Greek and Hebrew alphabets are available;  consult  RFC
          1345 for the appropriate sequences.  In addition, a set
          of two letter codes not in RFC 1345 are  available  for
          the  double-width  characters  corresponding  to  ASCII
          characters from !  to ~ (0x21 to 0x7e) by preceding the
          character  with ^, for example ^A for a double-width A.

          The following other two-character sequences are  under-

          ASCII characters
               These are already present on most keyboards:
          <(   Left square bracket
          //   Backslash (solidus)
          )>   Right square bracket
          (!   Left brace (curly bracket)
          !!   Vertical bar (pipe symbol)
          !)   Right brace (curly bracket)
          '?   Tilde

          Special letters
               Characters  found in various variants of the Latin
          ss   Eszett (scharfes S)
          D-, d-
          TH, th
          kk   Kra
          'n   'n
          NG, ng
          OI, oi
          yr   yr
          ED   ezh

          Currency symbols
          Ct   Cent
          Pd   Pound sterling (also lira and others)
          Cu   Currency
          Ye   Yen
          Eu   Euro (N.B. not in RFC 1345)

          Punctuation characters
               References to "right" quotes  indicate  the  shape

zsh 5.0.5          Last change: January 5, 2014                41

User Commands                                       ZSHCONTRIB(1)

               (like  a  9 rather than 6) rather than their gram-
               matical use.  (For example, a "right"  low  double
               quote is used to open quotations in German.)
          !I   Inverted exclamation mark
          BB   Broken vertical bar
          SE   Section
          Co   Copyright
          -a   Spanish feminine ordinal indicator
          <<   Left guillemet
          --   Soft hyphen
          Rg   Registered trade mark
          PI   Pilcrow (paragraph)
          -o   Spanish masculine ordinal indicator
          >>   Right guillemet
          ?I   Inverted question mark
          -1   Hyphen
          -N   En dash
          -M   Em dash
          -3   Horizontal bar
          :3   Vertical ellipsis
          .3   Horizontal midline ellipsis
          !2   Double vertical line
          =2   Double low line
          '6   Left single quote
          '9   Right single quote
          .9   "Right" low quote
          9'   Reversed "right" quote
          "6   Left double quote
          "9   Right double quote
          :9   "Right" low double quote
          9"   Reversed "right" double quote
          /-   Dagger
          /=   Double dagger

          Mathematical symbols
          DG   Degree
          -2, +-, -+
               - sign, +/- sign, -/+ sign
          2S   Superscript 2
          3S   Superscript 3
          1S   Superscript 1
          My   Micro
          .M   Middle dot
          14   Quarter
          12   Half
          34   Three quarters
          *X   Multiplication
          -:   Division
          %0   Per mille
          FA, TE, /0
               For all, there exists, empty set
          dP, DE, NB

zsh 5.0.5          Last change: January 5, 2014                42

User Commands                                       ZSHCONTRIB(1)

               Partial derivative, delta (increment), del (nabla)
          (-, -)
               Element of, contains
          *P, +Z
               Product, sum
          *-, Ob, Sb
               Asterisk, ring, bullet
          RT, 0(, 00
               Root sign, proportional to, infinity

          Other symbols
          cS, cH, cD, cC
               Card suits: spades, hearts, diamonds, clubs
          Md, M8, M2, Mb, Mx, MX
               Musical notation: crotchet (quarter note),  quaver
               (eighth note), semiquavers (sixteenth notes), flag
               sign, natural sign, sharp sign
          Fm, Ml
               Female, male

          Accents on their own
          '>   Circumflex (same as caret, ^)
          '!   Grave (same as backtick, `)
          ',   Cedilla
          ':   Diaeresis (Umlaut)
          'm   Macron
          ''   Acute

          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  com-
          mand line.

               bindkey '^Xf' insert-files

          When first executed, the user inputs a set of hexadeci-
          mal 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).

          See insert-composed-char for a way of inserting charac-
          ters using a two-character mnemonic.

     narrow-to-region [ -p pre ] [ -P post ]
         [ -S statepm | -R statepm ] [ -n ] [ start end ])
          Narrow the editable portion of the buffer to the region
          between the cursor and the mark, which may be in either

zsh 5.0.5          Last change: January 5, 2014                43

User Commands                                       ZSHCONTRIB(1)

          order.  The region may not be empty.

          narrow-to-region may be used as a widget or called as a
          function from a user-defined widget;  by  default,  the
          text  outside  the  editable  area  remains visible.  A
          recursive-edit is performed and the  original  widening
          status is then restored.  Various options and arguments
          are available when it is called as a function.

          The options -p pretext and -P posttext may be  used  to
          replace  the  text before and after the display for the
          duration of the function; either  or  both  may  be  an
          empty string.

          If  the  option  -n  is also given, pretext or posttext
          will only be inserted if there is text before or  after
          the region respectively which will be made invisible.

          Two  numeric  arguments may be given which will be used
          instead of the cursor and mark positions.

          The option -S statepm is used to  narrow  according  to
          the  other  options  while saving the original state in
          the parameter with name statepm, while  the  option  -R
          statepm  is  used to restore the state from the parame-
          ter; note in both cases the name of  the  parameter  is
          required.   In the second case, other options and argu-
          ments are irrelevant.  When this  method  is  used,  no
          recursive-edit  is performed; the calling widget should
          call this function with the option -S, perform its  own
          editing on the command line or pass control to the user
          via `zle recursive-edit', then call this function  with
          the option -R.  The argument statepm must be a suitable
          name for an ordinary parameter, except that  parameters
          beginning  with  the  prefix _ntr_ are reserved for use
          within narrow-to-region.  Typically the parameter  will
          be local to the calling function.

          narrow-to-region-invisible  is  a  simple  widget which
          calls narrow-to-region with arguments which replace any
          text outside the region with `...'.

          The  display  is restored (and the widget returns) upon
          any zle command which would usually cause the  line  to
          be  accepted or aborted.  Hence an additional such com-
          mand is required to accept or abort the current line.

          The return status of both widgets is zero if  the  line
          was accepted, else non-zero.

          Here  is  a trivial example of a widget using this fea-

zsh 5.0.5          Last change: January 5, 2014                44

User Commands                                       ZSHCONTRIB(1)

               local state
               narrow-to-region -p $'Editing restricted region\n' \
                 -P '' -S state
               zle recursive-edit
               narrow-to-region -R state

          This set  of  functions  implements  predictive  typing
          using history search.  After predict-on, typing charac-
          ters 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 stan-
          dard completion, and then inserts itself if no  comple-
          tions  were found.  However, editing in the middle of a
          line is liable to confuse prediction;  see  the  toggle
          style below.

          With  the  function  based  completion system (which is
          needed for this), you should be able  to  type  TAB  at
          almost  any  point  to  advance  the cursor to the next
          ``interesting'' character position (usually the end  of
          the current word, but sometimes somewhere in the middle
          of the word).  And of course as soon as the entire line
          is  what  you want, you can accept with return, without
          needing to move the cursor to the end first.

          The first time predict-on is used, it  creates  several
          additional widget functions:

               Replaces  the backward-delete-char widget.  You do
               not need to bind this yourself.
               Implements  predictive  typing  by  replacing  the
               self-insert  widget.  You do not need to bind this
               Turns off predictive typing.

          Although you autoload only the predict-on function,  it
          is  necessary to create a keybinding for predict-off as

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


zsh 5.0.5          Last change: January 5, 2014                45

User Commands                                       ZSHCONTRIB(1)

          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  cur-
          rent  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 edit-
          ing 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.

          If one argument is supplied to the function it is taken
          as  a prompt, otherwise `? ' is used.  If two arguments
          are supplied, they are the prompt and the initial value
          of $LBUFFER, and if a third argument is given it is the
          initial value of $RBUFFER.   This  provides  a  default
          value  and  starting cursor placement.  Upon return the
          entire buffer is the value of $REPLY.

          One option is available: `-k num'  specifies  that  num
          characters are to be read instead of a whole line.  The
          line editor is not invoked recursively in this case, so
          depending on the terminal settings the input may not be
          visible, and only the input keys are placed in  $REPLY,
          not  the  entire  buffer.   Note  that  unlike the read
          builtin num must be given; there is no default.

          The name is a slight misnomer, as in fact  the  shell's
          own minibuffer is not used.  Hence it is still possible
          to call executed-named-cmd and similar functions  while
          reading a value.

     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.

          If  the  widget  name  contains the word `pattern', for
          example by defining the widget using the  command  `zle
          -N  replace-pattern  replace-string', then the matching
          is performed using  zsh  patterns.   All  zsh  extended
          globbing  patterns  can  be  used in the source string;
          note that unlike filename generation the  pattern  does
          not  need  to  match an entire word, nor do glob quali-
          fiers have any effect.  In  addition,  the  replacement
          string  can contain parameter or command substitutions.
          Furthermore, a `&' in the replacement  string  will  be
          replaced   with   the  matched  source  string,  and  a

zsh 5.0.5          Last change: January 5, 2014                46

User Commands                                       ZSHCONTRIB(1)

          backquoted digit `\N'  will  be  replaced  by  the  Nth
          parenthesised  expression matched.  The form `\{N}' may
          be used to protect the digit from following digits.

          If the widget instead contains  the  word  `regex'  (or
          `regexp'), then the matching is performed using regular
          expressions,  respecting  the  setting  of  the  option
          RE_MATCH_PCRE (see the description of the function reg-
          exp-replace below).  The special replacement facilities
          described above for pattern matching are available.

          By  default  the  previous source or replacement string
          will not be offered for editing.  However, this feature
          can  be activated by setting the style edit-previous in
          the     context     :zle:widget      (for      example,
          :zle:replace-string)  to true.  In addition, a positive
          numeric argument  forces  the  previous  values  to  be
          offered, a negative or zero argument forces them not to

          The function replace-string-again can be used to repeat
          the  previous  replacement;  no  prompting is done.  As
          with replace-string, if the name of the widget contains
          the  word  `pattern'  or  `regex',  pattern  or regular
          expression matching is performed, else a literal string
          replacement.    Note   that  the  previous  source  and
          replacement text are the same whether pattern,  regular
          expression or string matching is used.

          In addition, replace-string shows the previous replace-
          ment above the prompt, so long as there was one  during
          the  current  session;  if  the source string is empty,
          that replacement will be repeated  without  the  widget
          prompting for a replacement string.

          For example, starting from the line:

               print This line contains fan and fond

          and  invoking  replace-pattern  with  the source string
          `f(?)n' and the replacement string `c\1r' produces  the
          not very useful line:

               print This line contains car and cord

          The  range  of the replacement string can be limited by
          using the narrow-to-region-invisible widget.  One limi-
          tation  of  the current version is that undo will cycle
          through changes to the replacement and  source  strings
          before undoing the replacement itself.


zsh 5.0.5          Last change: January 5, 2014                47

User Commands                                       ZSHCONTRIB(1)

          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 key-
          board.  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.

          If one argument is supplied to the function it is taken
          as a prompt, otherwise `Non-echoed text: ' is used  (as
          in emacs).  If a second and third argument are supplied
          they are used to begin and end the reference to $INVIS-
          IBLE  that is inserted into the buffer.  The default is
          to open with ${, then INVISIBLE, and close with },  but
          many other effects are possible.

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

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

          With a numeric prefix,  or  when  passed  command  line
          arguments  in  a  call  from another widget, it behaves
          like insert-last-word, except that  words  in  comments
          are ignored when INTERACTIVE_COMMENTS is set.

          Otherwise,  the rightmost ``interesting'' word from the
          previous command is found and  inserted.   The  default
          definition of ``interesting'' is that the word contains
          at least one alphabetic character, slash, or backslash.
          This  definition  may be overridden by use of the match
          style.  The context used to look up the  style  is  the
          widget    name,    so    usually    the    context   is
          :insert-last-word.  However, you can bind this function
          to different widgets to use different patterns:

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

          If  no  interesting word is found and the auto-previous
          style is set to a  true  value,  the  search  continues
          upward  through  the  history.   When  auto-previous is
          unset or  false  (the  default),  the  widget  must  be
          invoked  repeatedly  in order to search earlier history

zsh 5.0.5          Last change: January 5, 2014                48

User Commands                                       ZSHCONTRIB(1)

          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.

          Transpose  the  current line with the previous line and
          move the cursor to the start of the next line.  Repeat-
          ing  this  (which  can  be done by providing a positive
          numeric prefix argument) has the effect of  moving  the
          line above the cursor down by a number of lines.

          With  a  negative numeric prefix argument, requires two
          lines above the cursor.  These two lines are transposed
          and the cursor moved to the start of the previous line.
          Using a numeric prefix less than -1 has the  effect  of
          moving  the line above the cursor up by minus that num-
          ber of lines.

          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 con-
          tinues tracing the command word from the expanded alias
          until it reaches the command that will be executed.

          The style whence is available in the context :zle:$WID-
          GET; this may be set to an array to  give  the  command
          and  options  that will be used to investigate the com-
          mand word found.  The default is whence -c.

  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.

          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 white-
          space 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.

          The parameter REPLY is set to the index of the word  in
          reply  which  contains  the character after the cursor,

zsh 5.0.5          Last change: January 5, 2014                49

User Commands                                       ZSHCONTRIB(1)

          where the first element has  index  1.   The  parameter
          REPLY2  is  set to the index of the character under the
          cursor in that word,  where  the  first  character  has
          index 1.

          Hence  reply, REPLY and REPLY2 should all be made local
          to the enclosing function.

          See  the  function  modify-current-argument,  described
          below, for an example of how to call this function.

     modify-current-argument [ expr-using-$ARG | func ]
          This  function  provides  a  simple  method of allowing
          user-defined widgets to modify the command  line  argu-
          ment  under  the  cursor (or immediately to the left of
          the cursor if the cursor is between arguments).

          The argument can 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.

          Alternatively, if the argument  does  not  contain  the
          string  ARG,  it  is assumed to be a shell function, to
          which the current command line argument  is  passed  as
          the  only  argument.  The function should set the vari-
          able REPLY to the new value for the command line  argu-
          ment.  If the function returns non-zero status, so does
          the calling function.

          For example, a user-defined widget containing the  fol-
          lowing  code  converts  the  characters in the argument
          under the cursor into all upper case:

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

          The following strips any quoting from the current  word
          (whether  backslashes  or one of the styles of quotes),
          and replaces it with single quoting throughout:

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

          The following performs directory expansion on the  com-
          mand  line  argument  and  replaces  it by the absolute

               expand-dir() {
               modify-current-argument expand-dir

zsh 5.0.5          Last change: January 5, 2014                50

User Commands                                       ZSHCONTRIB(1)

          In practice the function expand-dir would probably  not
          be defined within the widget where modify-current-argu-
          ment is called.

     The behavior of several of the above  widgets  can  be  con-
     trolled  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.

          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  fur-
          ther effect. Like all styles used directly by incremen-
          tal-complete-word, this style is looked  up  using  the
          context `:incremental'.

          The  incremental-complete-word  and  insert-and-predict
          widgets set up  their  top-level  context  name  before
          calling  completion.  This allows one to define differ-
          ent 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 \

          It is a good idea to restrict the  completers  used  in
          prediction,  because  they may be automatically invoked
          as you type.  The _list  and  _menu  completers  should
          never be used with prediction.  The _approximate, _cor-
          rect, _expand, and _match completers may be  used,  but
          be  aware  that  they may change characters anywhere in
          the word behind the cursor, so you need to watch  care-
          fully that the result is what you intended.

          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:

               The  cursor  is  left where it was when completion

zsh 5.0.5          Last change: January 5, 2014                51

User Commands                                       ZSHCONTRIB(1)

               finished, but only if  it  is  after  a  character
               equal to the one just inserted by the user.  If it
               is after another character, this value is the same
               as `key'.

          key  The cursor is left after the nth occurrence of the
               character just inserted, where n is the number  of
               times  that  character appeared in the word before
               completion was attempted.  In short, this has  the
               effect  of  leaving the cursor after the character
               just typed even if the completion code  found  out
               that  no  other  characters need to be inserted at
               that position.

          Any other value for this style  unconditionally  leaves
          the  cursor  at  the position where the completion code
          left it.

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

          The insert-and-predict widget uses this style to decide
          if the completion should be shown even if there is only
          one  possible completion.  This is done if the value of
          this style is the string always.  In this case the con-
          text is `:predict' (not `:completion:predict').

          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:]/\\]*'

          However, you might want to include words  that  contain

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

          Or  include numbers as long as the word is at least two
          characters long:

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

          The above example causes redirections like "2>"  to  be

zsh 5.0.5          Last change: January 5, 2014                52

User Commands                                       ZSHCONTRIB(1)

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

          %c   Replaced  by  the  name  of the completer function
               that generated the matches  (without  the  leading

          %l   When  the  list style is set, replaced by `...' if
               the list of matches is too  long  to  fit  on  the
               screen and with an empty string otherwise.  If the
               list style is `false' or not set, `%l'  is  always

          %n   Replaced by the number of matches generated.

          %s   Replaced  by  `-no  match-',  `-no prefix-', or an
               empty string if there is  no  completion  matching
               the  word on the line, if the matches have no com-
               mon prefix different from the word on the line, or
               if there is such a common prefix, respectively.

          %u   Replaced  by  the unambiguous part of all matches,
               if there is any, and if it is different  from  the
               word on the line.

          Like  `break-keys',  this  uses the `:incremental' con-

          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 match-
          ing the pattern given as its value will stop  incremen-
          tal  completion and will then execute their usual func-

          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

zsh 5.0.5          Last change: January 5, 2014                53

User Commands                                       ZSHCONTRIB(1)

          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  dis-
          play  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.

          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

          Check the documentation for the calling widget or func-
          tion to determine whether the widget style is used.

     Two  functions  are provided to enable zsh to provide excep-
     tion handling in a form that should be familiar  from  other

     throw exception
          The  function  throw  throws  the named exception.  The
          name is an arbitrary string and is  only  used  by  the
          throw  and  catch  functions.   An exception is for the
          most part treated the same as a shell  error,  i.e.  an
          unhandled  exception  will cause the shell to abort all
          processing in a function or script and to return to the
          top level in an interactive shell.

     catch exception-pattern
          The  function catch returns status zero if an exception
          was thrown and the  pattern  exception-pattern  matches
          its  name.   Otherwise  it  returns  status  1.  excep-
          tion-pattern is a standard  shell  pattern,  respecting
          the  current  setting  of the EXTENDED_GLOB option.  An
          alias catch is also defined to prevent the argument  to
          the  function  from matching filenames, so patterns may
          be used unquoted.  Note that as exceptions are not fun-
          damentally different from other shell errors it is pos-
          sible to catch shell errors by using an empty string as
          the  exception  name.  The shell variable CAUGHT is set
          by catch to the name of the exception  caught.   It  is
          possible  to  rethrow an exception by calling the throw
          function again once an exception has been caught.

zsh 5.0.5          Last change: January 5, 2014                54

User Commands                                       ZSHCONTRIB(1)

     The functions are designed to  be  used  together  with  the
     always construct described in zshmisc(1).  This is important
     as only this construct provides  the  required  support  for
     exceptions.  A typical example is as follows.

            # "try" block
            # ... nested code here calls "throw MyExcept"
          } always {
            # "always" block
            if catch MyExcept; then
              print "Caught exception MyExcept"
            elif catch ''; then
              print "Caught a shell error.  Propagating..."
              throw ''
            # Other exceptions are not handled but may be caught further
            # up the call stack.

     If  all  exceptions  should  be  caught, the following idiom
     might be preferable.

            # ... nested code here throws an exception
          } always {
            if catch *; then
              case $CAUGHT in
                print "Caught my own exception"
                print "Caught some other exception"

     In common with exception handling in  other  languages,  the
     exception  may  be  thrown  by code deeply nested inside the
     `try' block.  However, note that it must  be  thrown  inside
     the  current shell, not in a subshell forked for a pipeline,
     parenthesised current-shell construct, or some form of  com-
     mand or process substitution.

     The  system  internally uses the shell variable EXCEPTION to
     record the name of the exception between throwing and catch-
     ing.   One  drawback of this scheme is that if the exception
     is not handled the variable EXCEPTION remains set and may be
     incorrectly  recognised  as  the  name  of an exception if a
     shell error subsequently occurs.  Adding unset EXCEPTION  at
     the  start  of  the  outermost  layer  of any code that uses

zsh 5.0.5          Last change: January 5, 2014                55

User Commands                                       ZSHCONTRIB(1)

     exception handling will eliminate this problem.

     Three functions are available to provide handling  of  files
     recognised  by  extension,  for  example  to dispatch a file when executed as a command to an appropriate viewer.

     zsh-mime-setup [ -fv ] [ -l [ suffix ... ] ]
     zsh-mime-handler [-l] command arguments ...
          These  two  functions  use  the files ~/.mime.types and
          /etc/mime.types, which associate types and  extensions,
          as well as ~/.mailcap and /etc/mailcap files, which as-
          sociate types and the programs that handle them.  These
          are provided on many systems with the Multimedia Inter-
          net Mail Extensions.

          To  enable  the  system,  the  function  zsh-mime-setup
          should  be  autoloaded and run.  This allows files with
          extensions to be treated as executable; such  files  be
          completed by the function completion system.  The func-
          tion zsh-mime-handler should not need to be  called  by
          the user.

          The  system  works  by  setting  up suffix aliases with
          `alias -s'.  Suffix aliases already  installed  by  the
          user will not be overwritten.

          For suffixes defined in lower case, upper case variants
          will also automatically be handled (e.g. PDF  is  auto-
          matically  handled  if  handling  for the suffix pdf is
          defined), but not vice versa.

          Repeated calls to zsh-mime-setup do  not  override  the
          existing  mapping between suffixes and executable files
          unless the option -f is  given.   Note,  however,  that
          this does not override existing suffix aliases assigned
          to handlers other than zsh-mime-handler.

          Calling zsh-mime-setup with the  option  -l  lists  the
          existing  mappings  without altering them.  Suffixes to
          list (which may contain pattern characters that  should
          be  quoted from immediate interpretation on the command
          line) may be given as additional  arguments,  otherwise
          all suffixes are listed.

          Calling  zsh-mime-setup  with the option -v causes ver-
          bose output to be shown during the setup operation.

          The system respects the mailcap flags needsterminal and
          copiousoutput, see mailcap(4).

zsh 5.0.5          Last change: January 5, 2014                56

User Commands                                       ZSHCONTRIB(1)

          The  functions  use  the  following  styles,  which are
          defined with the zstyle builtin  command  (see  zshmod-
          ules(1)).  They should be defined before zsh-mime-setup
          is run.  The contexts used all start with :mime:,  with
          additional components in some cases.  It is recommended
          that a trailing *  (suitably  quoted)  be  appended  to
          style  patterns  in  case  the  system  is  extended in
          future.  Some examples are given below.

          For files that have multiple  suffixes,  e.g.  .pdf.gz,
          where the context includes the suffix it will be looked
          up starting with the longest possible  suffix  until  a
          match  for the style is found.  For example, if .pdf.gz
          produces a match for the handler, that  will  be  used;
          otherwise the handler for .gz will be used.  Note that,
          owing to the way suffix  aliases  work,  it  is  always
          required  that there be a handler for the shortest pos-
          sible suffix, so in this example .pdf.gz  can  only  be
          handled  if .gz is also handled (though not necessarily
          in the same way).  Alternatively, if  no  handling  for
          .gz on its own is needed, simply adding the command

               alias -s gz=zsh-mime-handler

          to  the initialisation code is sufficient; .gz will not
          be handled on its own, but may be in  combination  with
          other suffixes.

               If this boolean style is true, the mailcap handler
               for the context in question is run using the  eval
               builtin  instead  of by starting a new sh process.
               This is more efficient, but may not  work  in  the
               occasional  cases  where  the mailcap handler uses
               strict POSIX syntax.

               If this boolean style is  true,  mailcap  handlers
               started  in  the background will be disowned, i.e.
               not subject  to  job  control  within  the  parent
               shell.   Such handlers nearly always produce their
               own windows,  so  the  only  likely  harmful  side
               effect  of  setting  the  style is that it becomes
               harder to kill jobs from within the shell.

               This style gives a list of patterns to be  matched
               against  files passed for execution with a handler
               program.  If the file  matches  the  pattern,  the
               entire  command  line  is  executed in its current
               form, with no handler.  This is useful  for  files
               which  might  have  suffixes  but  nonetheless  be

zsh 5.0.5          Last change: January 5, 2014                57

User Commands                                       ZSHCONTRIB(1)

               executable in their own right.  If  the  style  is
               not set, the pattern *(*) *(/) is used; hence exe-
               cutable files are executed directly and not passed
               to  a  handler, and the option AUTO_CD may be used
               to change to directories that happen to have  MIME

               This  style  is  useful  in  combination with exe-
               cute-as-is.  It is set to  an  array  of  patterns
               corresponding  to  full paths to files that should
               never be treated as executable, even if  the  file
               passed  to the MIME handler matches execute-as-is.
               This is useful for file systems that don't  handle
               execute  permission  or  that  contain executables
               from another operating system.   For  example,  if
               /mnt/windows is a Windows mount, then

                    zstyle ':mime:*' execute-never '/mnt/windows/*'

               will ensure that any files found in that area will
               be executed as MIME types even if  they  are  exe-
               cutable.  As this example shows, the complete file
               name is matched against the pattern, regardless of
               how  the file was passed to the handler.  The file
               is resolved to a full path using the  :A  modifier
               described  in  the  subsection  Modifers  in  zsh-
               expn(1).RE; this means  that  symbolic  links  are
               resolved  where possible, so that links into other
               file systems behave in the correct fashion.

               Used if the style find-file-in-path  is  true  for
               the  same context.  Set to an array of directories
               that are used for searching for  the  file  to  be
               handled;  the default is the command path given by
               the special  parameter  path.   The  shell  option
               PATH_DIRS is respected; if that is set, the appro-
               priate path will be searched even if the  name  of
               the  file  to be handled as it appears on the com-
               mand line contains a `/'.   The  full  context  is
               :mime:.suffix:,  as  described  for the style han-

               If set, allows files whose names  do  not  contain
               absolute  paths  to be searched for in the command
               path or the path specified by the file-path style.
               If the file is not found in the path, it is looked
               for locally (whether or not the current  directory
               is  in  the path); if it is not found locally, the
               handler will abort unless  the  handle-nonexistent

zsh 5.0.5          Last change: January 5, 2014                58

User Commands                                       ZSHCONTRIB(1)

               style  is set.  Files found in the path are tested
               as described for  the  style  execute-as-is.   The
               full  context  is :mime:.suffix:, as described for
               the style handler.

               Defines flags to go with a handler; the context is
               as for the handler style, and the format is as for
               the flags in mailcap.

               By default, arguments  that  don't  correspond  to
               files  are not passed to the MIME handler in order
               to prevent it from intercepting commands found  in
               the path that happen to have suffixes.  This style
               may be set to an array of extended  glob  patterns
               for  arguments  that will be passed to the handler
               even if they don't exist.  If it is not explicitly
               set  it  defaults  to [[:alpha:]]#:/* which allows
               URLs to be passed to the MIME handler even  though
               they  don't  exist in that format in the file sys-
               tem.   The  full  context  is  :mime:.suffix:,  as
               described for the style handler.

               Specifies  a  handler  for a suffix; the suffix is
               given by the context as  :mime:.suffix:,  and  the
               format  of the handler is exactly that in mailcap.
               Note in particular the `.' and trailing  colon  to
               distinguish  this  use of the context.  This over-
               rides any handler specified by the mailcap  files.
               If  the  handler  requires  a  terminal, the flags
               style should be set to include the word  needster-
               minal, or if the output is to be displayed through
               a pager (but  not  if  the  handler  is  itself  a
               pager), it should include copiousoutput.

               A  list  of  files in the format of ~/.mailcap and
               /etc/mailcap to be read  during  setup,  replacing
               the  default  list  which  consists  of  those two
               files.  The context is :mime:.  A +  in  the  list
               will be replaced by the default files.

               This  style  is  used  to resolve multiple mailcap
               entries for the same MIME type.  It consists of an
               array  of  the  following  elements, in descending
               order of priority; later entries will be  used  if
               earlier  entries are unable to resolve the entries
               being compared.  If none of the tests resolve  the
               entries,  the first entry encountered is retained.

zsh 5.0.5          Last change: January 5, 2014                59

User Commands                                       ZSHCONTRIB(1)

                    The order of files (entries  in  the  mailcap
                    style)  read.   Earlier  files are preferred.
                    (Note this does not resolve  entries  in  the
                    same file.)

                    The  priority  flag  from  the mailcap entry.
                    The priority is an integer from 0 to  9  with
                    the default value being 5.

                    The  test  given  by  the  mailcap-prio-flags
                    option is used to resolve entries.

                    Later entries are preferred; as  the  entries
                    are  strictly  ordered, this test always suc-

               Note that as this style is handled during initial-
               isation,  the  context  is  always :mime:, with no
               discrimination by suffix.

               This style is  used  when  the  keyword  flags  is
               encountered  in the list of tests specified by the
               mailcap-priorities style.  It should be set  to  a
               list  of patterns, each of which is tested against
               the flags specified in the mailcap entry (in other
               words,  the  sets  of  assignments found with some
               entries in the mailcap file).  Earlier patterns in
               the  list are preferred to later ones, and matched
               patterns are preferred to unmatched ones.

               A list of files in the format of ~/.mime.types and
               /etc/mime.types to be read during setup, replacing
               the default  list  which  consists  of  those  two
               files.   The  context  is :mime:.  A + in the list
               will be replaced by the default files.

               If this boolean style is set, the handler for  the
               given  context  is  always  run in the foreground,
               even if the flags provided in  the  mailcap  entry
               suggest  it  need  not be (for example, it doesn't
               require a terminal).

               If set, will be used instead of $PAGER or more  to
               handle  suffixes  where  the copiousoutput flag is

zsh 5.0.5          Last change: January 5, 2014                60

User Commands                                       ZSHCONTRIB(1)

               set.   The  context  is  as  for   handler,   i.e.
               :mime:.suffix:  for handling a file with the given


               zstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap
               zstyle ':mime:.txt:' handler less %s
               zstyle ':mime:.txt:' flags needsterminal

          When zsh-mime-setup is subsequently run, it  will  look
          for  mailcap  entries in the two files given.  Files of
          suffix .txt will be handled by running `less file.txt'.
          The flag needsterminal is set to show that this program
          must run attached to a terminal.

          As there are several steps to  dispatching  a  command,
          the  following  should be checked if attempting to exe-
          cute a  file  by  extension  .ext  does  not  have  the
          expected effect.

          The    command    `alias    -s    ext'    should   show
          `ps=zsh-mime-handler'.  If  it  shows  something  else,
          another  suffix alias was already installed and was not
          overwritten.  If  it  shows  nothing,  no  handler  was
          installed:   this is most likely because no handler was
          found in the .mime.types and  mailcap  combination  for
          .ext  files.  In that case, appropriate handling should
          be added to ~/.mime.types and mailcap.

          If the extension is handled by zsh-mime-handler but the
          file  is  not  opened  correctly,  either  the  handler
          defined for the type is incorrect, or the flags associ-
          ated with it are in appropriate.  Running zsh-mime-set-
          up -l will show the handler and, if there are any,  the
          flags.   A  %s  in  the handler is replaced by the file
          (suitably quoted if necessary).  Check that the handler
          program  listed  lists and can be run in the way shown.
          Also check that the flags needsterminal or  copiousout-
          put are set if the handler needs to be run under a ter-
          minal; the second flag is used if the output should  be
          sent  to  a  pager.   An  example of a suitable mailcap
          entry for such a program is:

               text/html; /usr/bin/lynx '%s'; needsterminal

          Running `zsh-mime-handler -l command line'  prints  the
          command  line  that  would  be  executed, simplified to
          remove the effect of any flags, and quoted so that  the
          output can be run as a complete zsh command line.  This
          is used by the completion system to decide how to  com-
          plete after a file handled by zsh-mime-setup.  )

zsh 5.0.5          Last change: January 5, 2014                61

User Commands                                       ZSHCONTRIB(1)

               This  function is separate from the two MIME func-
               tions described above and can be assigned directly
               to a suffix:

                    autoload -U pick-web-browser
                    alias -s html=pick-web-browser

               It is provided as an intelligent front end to dis-
               patch a web browser.  It may be run  as  either  a
               function  or  a  shell  script.  The status 255 is
               returned if no browser could be started.

               Various styles  are  available  to  customize  the
               choice of browsers:

                    The  value  of  the  style is an array giving
                    preferences in decreasing order for the  type
                    of  browser  to  use.  The values of elements
                    may be

                         Use a GUI browser that is  already  run-
                         ning  when an X Window display is avail-
                         able.   The  browsers  listed   in   the
                         x-browsers  style  are  tried  in  order
                         until one is found; if it is,  the  file
                         will  be  displayed  in that browser, so
                         the user may need to  check  whether  it
                         has  appeared.  If no running browser is
                         found, one  is  not  started.   Browsers
                         other  than Firefox, Opera and Konqueror
                         are assumed to  understand  the  Mozilla
                         syntax for opening a URL remotely.

                    x    Start a new GUI browser when an X Window
                         display is available.   Search  for  the
                         availability  of  one  of  the  browsers
                         listed in the x-browsers style and start
                         the  first  one that is found.  No check
                         is made for an already running  browser.

                    tty  Start  a terminal-based browser.  Search
                         for  the  availability  of  one  of  the
                         browsers   listed  in  the  tty-browsers
                         style and start the first  one  that  is

                    If the style is not set the default running x
                    tty is used.

zsh 5.0.5          Last change: January 5, 2014                62

User Commands                                       ZSHCONTRIB(1)

                    An array in decreasing order of preference of
                    browsers to use when running under the X Win-
                    dow System.  The array consists of  the  com-
                    mand  name  under which to start the browser.
                    They are looked  up  in  the  context  :mime:
                    (which  may be extended in future, so append-
                    ing `*' is recommended).  For example,

                         zstyle ':mime:*' x-browsers opera konqueror firefox

                    specifies that pick-web-browser should  first
                    look  for  a  running instance of Opera, Kon-
                    queror or Firefox, in that order, and  if  it
                    fails  to  find  any  should attempt to start
                    Opera.   The  default  is   firefox   mozilla
                    netscape opera konqueror.

                    An  array  similar to x-browsers, except that
                    it gives browsers to use  when  no  X  Window
                    display  is available.  The default is elinks
                    links lynx.

                    If it is set this style is used to  pick  the
                    command  used  to  open a page for a browser.
                    The context is :mime:browser:new:$browser: to
                    start  a  new  browser  or :mime:browser:run-
                    ning:$browser: to open a  URL  in  a  browser
                    already  running  on  the  current X display,
                    where $browser is the value  matched  in  the
                    x-browsers or tty-browsers style.  The escape
                    sequence %b in  the  style's  value  will  be
                    replaced  by  the  browser,  while %u will be
                    replaced by the URL.  If  the  style  is  not
                    set,  the  default  for  all new instances is
                    equivalent to %b  %u  and  the  defaults  for
                    using  running browsers are equivalent to the
                    values kfmclient openURL  %u  for  Konqueror,
                    firefox  -new-tab %u for Firefox, opera -new-
                    page   %u   for   Opera,   and   %b   -remote
                    "openUrl(%u)" for all others.

     zcalc [ -ef ] [ expression ... ]
          A  reasonably powerful calculator based on zsh's arith-
          metic evaluation facility.  The syntax  is  similar  to
          that of formulae in most programming languages; see the
          section  `Arithmetic  Evaluation'  in  zshmisc(1)   for
          details.  The mathematical library zsh/mathfunc will be
          loaded  if  it  is  available;  see  the  section  `The

zsh 5.0.5          Last change: January 5, 2014                63

User Commands                                       ZSHCONTRIB(1)

          zsh/mathfunc  Module' in zshmodules(1).  The mathemati-
          cal functions correspond to the raw  system  libraries,
          so trigonometric functions are evaluated using radians,
          and so on.

          Each line typed is evaluated  as  an  expression.   The
          prompt  shows  a  number,  which corresponds to a posi-
          tional parameter where the result of  that  calculation
          is  stored.  For example, the result of the calculation
          on the line preceded by `4> ' is available as $4.   The
          last  value  calculated is available as ans.  Full com-
          mand line editing, including the  history  of  previous
          calculations, is available; the history is saved in the
          file ~/.zcalc_history.  To exit, enter a blank line  or
          type  `:q'  on  its  own (`q' is allowed for historical

          A line ending with a single backslash is treated in the
          same  fashion  as  it  is in command line editing:  the
          backslash is removed, the  function  prompts  for  more
          input  (the  prompt  is  preceded  by `...' to indicate
          this), and the lines are combined into one to  get  the
          final  result.   In  addition, if the input so far con-
          tains more  open  than  close  parentheses  zcalc  will
          prompt for more input.

          If  arguments  are given to zcalc on start up, they are
          used to prime the first few positional  parameters.   A
          visual  indication of this is given when the calculator

          The constants PI (3.14159...) and  E  (2.71828...)  are
          provided.   Parameter  assignment is possible, but note
          that all parameters will be put into the global  names-

          The  output  base  can  be  initialised  by passing the
          option `-#base', for example `zcalc -#16' (the `#'  may
          have  to  be  quoted, depending on the globbing options

          If the option `-e' is set, the function runs non-inter-
          actively:  the  arguments are treated as expressions to
          be evaluated as if entered interactively line by  line.

          If  the  option `-f' is set, all numbers are treated as
          floating point, hence for example the expression  `3/4'
          evaluates  to  0.75 rather than 0.  Options must appear
          in separate words.

          The prompt is  configurable  via  the  parameter  ZCAL-
          CPROMPT,  which  undergoes  standard  prompt expansion.

zsh 5.0.5          Last change: January 5, 2014                64

User Commands                                       ZSHCONTRIB(1)

          The index of the current entry is stored locally in the
          first element of the array psvar, which can be referred
          to in ZCALCPROMPT as  `%1v'.   The  default  prompt  is
          `%1v> '.

          A  few special commands are available; these are intro-
          duced by a  colon.   For  backward  compatibility,  the
          colon  may be omitted for certain commands.  Completion
          is available if compinit has been run.

          The output precision may be specified within  zcalc  by
          special commands familiar from many calculators.
               The  default output format.  It corresponds to the
               printf %g specification.  Typically this shows six
               decimal digits.

          :sci digits
               Scientific  notation,  corresponding to the printf
               %g output format with the precision given by  dig-
               its.  This produces either fixed point or exponen-
               tial notation depending on the value output.

          :fix digits
               Fixed point notation, corresponding to the  printf
               %f  output format with the precision given by dig-

          :eng digits
               Exponential notation, corresponding to the  printf
               %E  output format with the precision given by dig-

          :raw Raw output:  this is the default form of the  out-
               put  from  a  math evaluation.  This may show more
               precision than the number actually possesses.

          Other special commands:
               Execute line... as a normal  shell  command  line.
               Note  that  it  is  executed in the context of the
               function, i.e. with  local  variables.   Space  is
               optional after :!.

          :local arg ...
               Declare  variables  local  to  the function.  Note
               that certain variables are used  by  the  function
               for  its  own  purposes.   Other  variables may be
               used, too, but they will be taken from or put into
               the global scope.

          :function name [ body ]

zsh 5.0.5          Last change: January 5, 2014                65

User Commands                                       ZSHCONTRIB(1)

               Define  a  mathematical function or (with no body)
               delete it.  :function may be abbreviated to  :func
               or simply :f.  The name may contain the same char-
               acters as a shell function name.  The function  is
               defined using zmathfuncdef, see below.

               Note  that zcalc takes care of all quoting.  Hence
               for example:

                    :f cube $1 * $1 * $1

               defines a function to cube the sole argument.

               This is not a special command, rather part of nor-
               mal  arithmetic  syntax;  however,  when this form
               appears on a line by  itself  the  default  output
               radix  is  set to base.  Use, for example, `[#16]'
               to display hexadecimal output preceded by an indi-
               cation  of  the  base, or `[##16]' just to display
               the raw number in the  given  base.   Bases  them-
               selves  are  always  specified  in  decimal. `[#]'
               restores the normal output format.  Note that set-
               ting an output base suppresses floating point out-
               put; use `[#]' to return to normal operation.

          See the comments in the function for a few extra  tips.

     zmathfuncdef [ mathfunc [ body ] ]
          A convenient front end to functions -M.

          With  two  arguments,  define  a  mathematical function
          named mathfunc which can be used in any form of  arith-
          metic evaluation.  body is a mathematical expression to
          implement the function.  It may contain  references  to
          position  parameters $1, $2, ...  to refer to mandatory
          parameters and ${1:-defvalue} ...  to refer to optional
          parameters.   Note  that  the  forms  must  be strictly
          adhered to for the function to  calculate  the  correct
          number  of  arguments.  The implementation is held in a
          shell function  named  zsh_math_func_mathfunc;  usually
          the  user  will not need to refer to the shell function
          directly.  Any existing function of the  same  name  is
          silently replaced.

          With  one  argument,  remove  the mathematical function
          mathfunc as well as the shell function  implementation.

          With  no  arguments,  list  all mathfunc functions in a
          form suitable for restoring the definition.  The  func-
          tions  have  not  necessarily  been  defined  by zmath-

zsh 5.0.5          Last change: January 5, 2014                66

User Commands                                       ZSHCONTRIB(1)

     The zsh/newuser module comes with a function to aid in  con-
     figuring  shell  options  for  new  users.  If the module is
     installed, this function can also be run  by  hand.   It  is
     available  even  if  the  module's default behaviour, namely
     running the function for  a  new  user  logging  in  without
     startup files, is inhibited.

     zsh-newuser-install [ -f ]
          The function presents the user with various options for
          customizing their  initialization  scripts.   Currently
          only  ~/.zshrc  is  handled.   $ZDOTDIR/.zshrc  is used
          instead if the parameter ZDOTDIR is set; this  provides
          a way for the user to configure a file without altering
          an existing .zshrc.

          By default the function exits immediately if  it  finds
          any of the files .zshenv, .zprofile, .zshrc, or .zlogin
          in  the  appropriate  directory.   The  option  -f   is
          required  in  order  to force the function to continue.
          Note this may happen even if  .zshrc  itself  does  not

          As currently configured, the function will exit immedi-
          ately if the user has root privileges;  this  behaviour
          cannot be overridden.

          Once activated, the function's behaviour is supposed to
          be self-explanatory.  Menus are  present  allowing  the
          user  to  alter  the  value  of options and parameters.
          Suggestions for improvements are always welcome.

          When the script exits, the user is given  the  opportu-
          nity to save the new file or not; changes are not irre-
          versible until this  point.   However,  the  script  is
          careful to restrict changes to the file only to a group
          marked  by   the   lines   `#   Lines   configured   by
          zsh-newuser-install'  and `# End of lines configured by
          zsh-newuser-install'.  In addition, the old version  of
          .zshrc  is  saved  to  a  file  with  the  suffix  .zni

          If the function edits an existing .zshrc, it is  up  to
          the  user  to  ensure  that  the changes made will take
          effect.  For example, if control usually returns  early
          from  the  existing  .zshrc  the lines will not be exe-
          cuted; or a  later  initialization  file  may  override
          options  or parameters, and so on.  The function itself
          does not attempt to detect any such conflicts.


zsh 5.0.5          Last change: January 5, 2014                67

User Commands                                       ZSHCONTRIB(1)

     There are a large number of helpful functions in  the  Func-
     tions/Misc directory of the zsh distribution.  Most are very
     simple and do not require documentation here, but a few  are
     worthy of special mention.

          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.

          The  eight  base colors are: black, red, green, yellow,
          blue, magenta, cyan, and  white.   Each  of  these  has
          codes for foreground and background.  In addition there
          are eight intensity attributes: bold, faint,  standout,
          underline, blink, reverse, and conceal.  Finally, there
          are six codes used to negate  attributes:  none  (reset
          all  attributes  to the defaults), normal (neither bold
          nor faint), no-standout,  no-underline,  no-blink,  and

          Some  terminals do not support all combinations of col-
          ors and intensities.

          The associative arrays are:

               Map all the color names to  their  integer  codes,
               and  integer  codes to the color names.  The eight
               base names map to the foreground color  codes,  as
               do  names  prefixed  with `fg-', such as `fg-red'.
               Names prefixed  with  `bg-',  such  as  `bg-blue',
               refer  to  the background codes.  The reverse map-
               ping from code to color yields base name for fore-
               ground codes and the bg- form for backgrounds.

               Although  it  is a misnomer to call them `colors',
               these  arrays  also   map   the   other   fourteen
               attributes from names to codes and codes to names.

               Map the eight basic color names to  ANSI  terminal
               escape  sequences that set the corresponding fore-
               ground text properties.  The fg  sequences  change
               the  color  without  changing  the eight intensity

zsh 5.0.5          Last change: January 5, 2014                68

User Commands                                       ZSHCONTRIB(1)

               Map the eight basic color names to  ANSI  terminal
               escape  sequences that set the corresponding back-
               ground properties.  The bg  sequences  change  the
               color   without   changing   the  eight  intensity

          In addition,  the  scalar  parameters  reset_color  and
          bold_color  are  set  to the ANSI terminal escapes that
          turn off all attributes and  turn  on  bold  intensity,

     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 sepa-
          rated 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-num-
          ber  parts  ignored.   If one string has fewer segments
          than the other, the  missing  segments  are  considered

          This  is  useful  in  startup  files to set options and
          other state that are not available in all  versions  of

               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 pro-
          vides  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'.

          See also the pager, prompt and rprompt styles below.

     regexp-replace var regexp replace
          Use regular expressions to perform a global search  and

zsh 5.0.5          Last change: January 5, 2014                69

User Commands                                       ZSHCONTRIB(1)

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

          var  is  the name of the variable containing the string
          to be matched.  The variable will be modified  directly
          by  the  function.   The variables MATCH, MBEGIN, MEND,
          match, mbegin, mend should be avoided as these are used
          by the regular expression code.

          regexp  is  the regular expression to match against the

          replace is the  replacement  text.   This  can  contain
          parameter,  command  and  arithmetic  expressions which
          will be replaced:  in particular, a reference to $MATCH
          will be replaced by the text matched by the pattern.

          The  return  status is 0 if at least one match was per-
          formed, else 1.

     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.

          In  the discussion which follows, if cmd is a file sys-
          tem path, it is first reduced to its  rightmost  compo-
          nent (the file name).

          Help is first sought by looking for a file named cmd in
          the directory named by the HELPDIR  parameter.   If  no
          file is found, an assistant function, alias, or command
          named run-help-cmd is sought.  If found, the  assistant
          is  executed  with the rest of the current command line
          (everything after the command name cmd)  as  its  argu-
          ments.   When  neither file nor assistant is found, the
          external command `man cmd' is run.

          An example assistant for the "ssh" command:

               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
                   if [[ ${#args} -lt 2 ]]; then
                       man ssh

zsh 5.0.5          Last change: January 5, 2014                70

User Commands                                       ZSHCONTRIB(1)

                       run-help $args[2]

          Several of these assistants are provided in  the  Func-
          tions/Misc  directory.   These  must  be autoloaded, or
          placed as executable scripts in your  search  path,  in
          order to be found and used by run-help.

               Assistant functions for the git, svk, and svn com-

          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.

          This function must be used as a ZLE widget:

               autoload -U tetris
               zle -N tetris
               bindkey keys tetris

          To start a game, execute the widget by typing the keys.
          Whatever  command line you were editing disappears tem-
          porarily, and your keymap is also temporarily  replaced
          by  the Tetris control keys.  The previous editor state
          is restored when you quit the game (by pressing `q') or
          when you lose.

          If  you  quit in the middle of a game, the next invoca-
          tion of the tetris widget will continue where you  left
          off.  If you lost, it will start a new game.

     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.

          The option list represents options of the zargs command
          itself,  which  are  the  same  as those of xargs.  The
          input list is the collection  of  strings  (often  file
          names)  that  become  the  arguments  of  the  command,

zsh 5.0.5          Last change: January 5, 2014                71

User Commands                                       ZSHCONTRIB(1)

          analogous to the standard input of xargs.  Finally, the
          arg  list consists of those arguments (usually options)
          that are passed to the command each time it runs.   The
          arg  list  precedes the elements from the input list in
          each run.  If no command is provided, then no arg  list
          may  be provided, and in that event the default command
          is `print' with arguments `-r --'.

          For example, to get a long  ls  listing  of  all  plain
          files in the current directory or its subdirectories:

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

          Note  that  `--'  is  used  both to mark the end of the
          option list and to mark the end of the input  list,  so
          it  must  appear  twice  whenever the input list may be
          empty.  If there is guaranteed to be at least one input
          and the first input does not begin with a `-', then the
          first `--' may be omitted.

          In the event that the string  `--'  is  or  may  be  an
          input,  the  -e  option  may  be  used  to  change  the
          end-of-inputs marker.  Note that this does  not  change
          the end-of-options marker.  For example, to use `..' as
          the marker:

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

          This is a good choice in that example because no  plain
          file can be named `..', but the best end-marker depends
          on the circumstances.

          The options -i, -I, -l, -L, and -n differ slightly from
          their  usage  in  xargs.   There are no input lines for
          zargs to count, so -l and -L count  through  the  input
          list,  and  -n counts the number of arguments passed to
          each execution of  command,  including  any  arg  list.
          Also,  any  time  -i  or -I is used, each input is pro-
          cessed separately as if by `-L 1'.

          For details of the other zargs  options,  see  xargs(1)
          (but  note the difference in function between zargs and
          xargs) or run zargs with the --help option.

     zed [ -f ] name
     zed -b
          This function uses the ZLE editor to  edit  a  file  or

          Only one name argument is allowed.  If the -f option is
          given, the name is taken to be that of a  function;  if

zsh 5.0.5          Last change: January 5, 2014                72

User Commands                                       ZSHCONTRIB(1)

          the  function  is  marked for autoloading, zed searches
          for it in the fpath and loads it.  Note that  functions
          edited  this  way are installed into the current shell,
          but not written back to the autoload file.

          Without -f, name is the path name of the file to  edit,
          which need not exist; it is created on write, if neces-

          While editing, the function sets the main keymap to zed
          and  the vi command keymap to zed-vicmd.  These will be
          copied from the existing main and vicmd keymaps if they
          do  not  exist  the first time zed is run.  They can be
          used to provide special key bindings used only in  zed.

          If it creates the keymap, zed rebinds the return key to
          insert a line break and `^X^W' to accept  the  edit  in
          the  zed  keymap,  and binds `ZZ' to accept the edit in
          the zed-vicmd keymap.

          The bindings alone can be  installed  by  running  `zed
          -b'.  This is suitable for putting into a startup file.
          Note that, if rerun, this will overwrite  the  existing
          zed and zed-vicmd keymaps.

          Completion is available, and styles may be set with the
          context prefix `:completion:zed'.

          A zle widget zed-set-file-name is available.  This  can
          be   called   by   name  from  within  zed  using  `\ex
          zed-set-file-name'  (note,  however,  that  because  of
          zed's  rebindings  you  will have to type ^j at the end
          instead of the return key), or can be bound to a key in
          either  of  the zed or zed-vicmd keymaps after `zed -b'
          has been run.  When the widget is  called,  it  prompts
          for  a  new  name  for the file being edited.  When zed
          exits the file will be written under that name and  the
          original  file  will  be left alone.  The widget has no
          effect with `zed -f'.

          While zed-set-file-name is running, zed uses the keymap
          zed-normal-keymap, which is linked from the main keymap
          in effect at the time  zed  initialised  its  bindings.
          (This is to make the return key operate normally.)  The
          result is that if the main keymap has been changed, the
          widget  won't  notice.   This is not a concern for most

     zcp [ -finqQvwW ] srcpat dest
     zln [ -finqQsvwW ] srcpat dest
          Same as zmv -C and zmv -L, respectively.   These  func-
          tions do not appear in the zsh distribution, but can be

zsh 5.0.5          Last change: January 5, 2014                73

User Commands                                       ZSHCONTRIB(1)

          created by linking zmv to the names zcp and zln in some
          directory in your fpath.

     zkbd See `Keyboard Definition' above.

string ] srcpat dest
     zmv  [  -finqQsvwW  ]  [ -C | -L | -M | -[pP] program ] [ -o
          Move  (usually, rename) files matching the pattern src-
          pat to corresponding files having  names  of  the  form
          given  by  dest, where srcpat contains parentheses sur-
          rounding patterns which will be replaced in turn by $1,
          $2, ... in dest.  For example,

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

          renames  `foo.lis'  to `foo.txt', `my.old.stuff.lis' to
          `my.old.stuff.txt', and so on.

          The pattern is always treated as an EXTENDED_GLOB  pat-
          tern.   Any  file whose name is not changed by the sub-
          stitution is simply ignored.  Any error (a substitution
          resulted in an empty string, two substitutions gave the
          same result, the destination was  an  existing  regular
          file  and  -f was not given) causes the entire function
          to abort without doing anything.


          -f   Force overwriting of destination files.  Not  cur-
               rently  passed down to the mv/cp/ln command due to
               vagaries of implementations (but you can use  -o-f
               to do that).
          -i   Interactive: show each line to be executed and ask
               the user whether to execute it.  `Y' or  `y'  will
               execute it, anything else will skip it.  Note that
               you just need to type one character.
          -n   No execution: print what would happen,  but  don't
               do it.
          -q   Turn  bare  glob  qualifiers  off:  now assumed by
               default, so this has no effect.
          -Q   Force bare glob qualifiers on.  Don't turn this on
               unless you are actually using glob qualifiers in a
          -s   Symbolic, passed down to ln; only works with -L.
          -v   Verbose: print each command  as  it's  being  exe-
          -w   Pick   out  wildcard  parts  of  the  pattern,  as
               described above, and  implicitly  add  parentheses
               for referring to them.
          -W   Just  like  -w, with the addition of turning wild-
               cards in the replacement pattern  into  sequential

zsh 5.0.5          Last change: January 5, 2014                74

User Commands                                       ZSHCONTRIB(1)

               ${1} .. ${N} references.
          -M   Force  cp,  ln  or mv, respectively, regardless of
               the name of the function.
          -p program
               Call program instead of cp, ln or mv.  Whatever it
               does, it should at least understand the form `pro-
               gram -- oldname newname' where oldname and newname
               are  filenames  generated by zmv.  program will be
               split into words, so might be e.g. the name of  an
               archive tool plus a copy or rename subcommand.
          -P program
               As -p program, except that program does not accept
               a following -- to indicate the end of options.  In
               this case filenames must already be in a sane form
               for the program in question.
          -o optstring
               The optstring is split into words and passed  down
               verbatim  to  the  cp,  ln or mv command called to
               perform the work.  It should probably begin with a

          Further examples:

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

          For any file in the current directory with at least one
          space in the name, replace every space by an underscore
          and display the commands executed.

          For  more  complete  examples  and other implementation
          details, see the zmv source file,  usually  located  in
          one of the directories named in your fpath, or in Func-
          tions/Misc/zmv in the zsh distribution.

          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

          This defines `style1' with  `value1'  for  the  context
          :foo:bar  as  usual,  but it also defines `style2' with
          `value2' for the context :foo:bar:baz and `style3' with

zsh 5.0.5          Last change: January 5, 2014                75

User Commands                                       ZSHCONTRIB(1)

          `value3'  for :foo:bar:frob.  Any subcontext may be the
          empty string to re-use the first context unchanged.

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

          The  nslookup  function looks up this style in the con-
          text `:nslookup' to determine the program used to  dis-
          play output that does not fit on a single screen.

          The  nslookup  function looks up this style in the con-
          text `: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)).

     See   attributes(5)   for   descriptions  of  the  following

     |Availability   | shell/zsh        |
     |Stability      | Volatile         |
     This  software  was   built   from   source   available   at    The  original
     community   source   was   downloaded   from    http://down-

     Further information about this software can be found on  the
     open source community website at

zsh 5.0.5          Last change: January 5, 2014                76