1ZSHALL(1)                   General Commands Manual                  ZSHALL(1)
2
3
4

NAME

6       zshall - the Z shell meta-man page
7

OVERVIEW

9       Because  zsh contains many features, the zsh manual has been split into
10       a number of sections.  This manual page includes all the separate  man‐
11       ual pages in the following order:
12
13       zshroadmap   Informal introduction to the manual
14       zshmisc      Anything not fitting into the other sections
15       zshexpn      Zsh command and parameter expansion
16       zshparam     Zsh parameters
17       zshoptions   Zsh options
18       zshbuiltins  Zsh built-in functions
19       zshzle       Zsh command line editing
20       zshcompwid   Zsh completion widgets
21       zshcompsys   Zsh completion system
22       zshcompctl   Zsh completion control
23       zshmodules   Zsh loadable modules
24       zshcalsys    Zsh built-in calendar functions
25       zshtcpsys    Zsh built-in TCP functions
26       zshzftpsys   Zsh built-in FTP client
27       zshcontrib   Additional zsh functions and utilities
28

DESCRIPTION

30       Zsh  is  a  UNIX  command  interpreter (shell) usable as an interactive
31       login shell and as a shell script command processor.  Of  the  standard
32       shells,  zsh most closely resembles ksh but includes many enhancements.
33       Zsh has command line editing, builtin spelling correction, programmable
34       command completion, shell functions (with autoloading), a history mech‐
35       anism, and a host of other features.
36

AUTHOR

38       Zsh was originally written by Paul Falstad <pf@zsh.org>.   Zsh  is  now
39       maintained  by  the  members of the zsh-workers mailing list <zsh-work‐
40       ers@zsh.org>.   The  development  is  currently  coordinated  by  Peter
41       Stephenson <pws@zsh.org>.  The coordinator can be contacted at <coordi‐
42       nator@zsh.org>, but matters relating to the code should generally go to
43       the mailing list.
44

AVAILABILITY

46       Zsh  is available from the following anonymous FTP sites.  These mirror
47       sites are kept frequently up to date.  The sites marked with (H) may be
48       mirroring ftp.cs.elte.hu instead of the primary site.
49
50       Primary site
51              ftp://ftp.zsh.org/pub/
52              http://www.zsh.org/pub/
53
54       Australia
55              ftp://ftp.zsh.org/pub/
56              http://www.zsh.org/pub/
57              http://mirror.dejanseo.com.au/pub/zsh/
58
59       Hungary
60              ftp://ftp.cs.elte.hu/pub/zsh/
61              http://www.cs.elte.hu/pub/zsh/
62
63              The  up-to-date  source  code is available via anonymous CVS and
64              Git from Sourceforge.  See  http://sourceforge.net/projects/zsh/
65              for  details.  A summary of instructions for the CVS and Git ar‐
66              chives can be found at http://zsh.sourceforget.net/.
67

MAILING LISTS

69       Zsh has 3 mailing lists:
70
71       <zsh-announce@zsh.org>
72              Announcements about releases, major changes in the shell and the
73              monthly posting of the Zsh FAQ.  (moderated)
74
75       <zsh-users@zsh.org>
76              User discussions.
77
78       <zsh-workers@zsh.org>
79              Hacking, development, bug reports and patches.
80
81       To subscribe or unsubscribe, send mail to the associated administrative
82       address for the mailing list.
83
84       <zsh-announce-subscribe@zsh.org>
85       <zsh-users-subscribe@zsh.org>
86       <zsh-workers-subscribe@zsh.org>
87       <zsh-announce-unsubscribe@zsh.org>
88       <zsh-users-unsubscribe@zsh.org>
89       <zsh-workers-unsubscribe@zsh.org>
90
91       YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED.  All
92       submissions  to  zsh-announce are automatically forwarded to zsh-users.
93       All submissions to zsh-users are automatically forwarded  to  zsh-work‐
94       ers.
95
96       If  you  have  problems subscribing/unsubscribing to any of the mailing
97       lists, send mail to <listmaster@zsh.org>.  The mailing lists are  main‐
98       tained by Karsten Thygesen <karthy@kom.auc.dk>.
99
100       The  mailing  lists  are archived; the archives can be accessed via the
101       administrative addresses listed above.  There is also a  hypertext  ar‐
102       chive,   maintained   by   Geoff   Wing   <gcw@zsh.org>,  available  at
103       http://www.zsh.org/mla/.
104

THE ZSH FAQ

106       Zsh has a list of Frequently Asked Questions (FAQ), maintained by Peter
107       Stephenson  <pws@zsh.org>.   It  is  regularly  posted to the newsgroup
108       comp.unix.shell and the zsh-announce mailing list.  The latest  version
109       can    be    found   at   any   of   the   Zsh   FTP   sites,   or   at
110       http://www.zsh.org/FAQ/.  The contact address for  FAQ-related  matters
111       is <faqmaster@zsh.org>.
112

THE ZSH WEB PAGE

114       Zsh  has  a  web page which is located at http://www.zsh.org/.  This is
115       maintained by Karsten Thygesen <karthy@zsh.org>,  of  SunSITE  Denmark.
116       The contact address for web-related matters is <webmaster@zsh.org>.
117

THE ZSH USERGUIDE

119       A  userguide is currently in preparation.  It is intended to complement
120       the manual, with explanations and hints on issues where the manual  can
121       be cabbalistic, hierographic, or downright mystifying (for example, the
122       word `hierographic' does not exist).  It can be viewed in  its  current
123       state  at  http://zsh.sourceforge.net/Guide/.   At the time of writing,
124       chapters dealing with startup files and their contents and the new com‐
125       pletion system were essentially complete.
126

THE ZSH WIKI

128       A  `wiki'  website for zsh has been created at http://www.zshwiki.org/.
129       This is a site which can be added to and  modified  directly  by  users
130       without any special permission.  You can add your own zsh tips and con‐
131       figurations.
132

INVOCATION

134       The following flags are interpreted by the shell when invoked to deter‐
135       mine where the shell will read commands from:
136
137       -c     Take  the  first  argument  as a command to execute, rather than
138              reading commands from a script or standard input.  If  any  fur‐
139              ther  arguments  are  given,  the  first  one is assigned to $0,
140              rather than being used as a positional parameter.
141
142       -i     Force shell to be interactive.  It is still possible to  specify
143              a script to execute.
144
145       -s     Force shell to read commands from the standard input.  If the -s
146              flag is not present and an argument is given, the first argument
147              is taken to be the pathname of a script to execute.
148
149       If  there are any remaining arguments after option processing, and nei‐
150       ther of the options -c or -s was supplied, the first argument is  taken
151       as  the file name of a script containing shell commands to be executed.
152       If the option PATH_SCRIPT is set, and the file name does not contain  a
153       directory  path  (i.e.  there is no `/' in the name), first the current
154       directory and then the command path given  by  the  variable  PATH  are
155       searched  for  the  script.   If the option is not set or the file name
156       contains a `/' it is used directly.
157
158       After the  first  one  or  two  arguments  have  been  appropriated  as
159       described above, the remaining arguments are assigned to the positional
160       parameters.
161
162       For further options,  which  are  common  to  invocation  and  the  set
163       builtin, see zshoptions(1).
164
165       Options  may  be specified by name using the -o option.  -o acts like a
166       single-letter option, but takes a following string as the option  name.
167       For example,
168
169              zsh -x -o shwordsplit scr
170
171       runs  the  script  scr,  setting the XTRACE option by the corresponding
172       letter `-x' and the SH_WORD_SPLIT  option  by  name.   Options  may  be
173       turned  off  by  name  by using +o instead of -o.  -o can be stacked up
174       with preceding single-letter options, so for example `-xo  shwordsplit'
175       or `-xoshwordsplit' is equivalent to `-x -o shwordsplit'.
176
177       Options  may  also  be  specified  by  name  in  GNU long option style,
178       `--option-name'.  When this is done, `-' characters in the option  name
179       are permitted: they are translated into `_', and thus ignored.  So, for
180       example, `zsh  --sh-word-split'  invokes  zsh  with  the  SH_WORD_SPLIT
181       option  turned  on.   Like other option syntaxes, options can be turned
182       off by replacing the initial `-' with a `+'; thus `+-sh-word-split'  is
183       equivalent  to  `--no-sh-word-split'.   Unlike  other  option syntaxes,
184       GNU-style long options cannot be stacked with any other options, so for
185       example  `-x-shwordsplit'  is  an error, rather than being treated like
186       `-x --shwordsplit'.
187
188       The special GNU-style option `--version' is handled; it sends to  stan‐
189       dard  output  the shell's version information, then exits successfully.
190       `--help' is also handled; it sends to standard output a list of options
191       that can be used when invoking the shell, then exits successfully.
192
193       Option  processing  may  be finished, allowing following arguments that
194       start with `-' or `+' to be treated as normal arguments, in  two  ways.
195       Firstly,  a lone `-' (or `+') as an argument by itself ends option pro‐
196       cessing.  Secondly, a special option `--' (or `+-'), which may be spec‐
197       ified  on its own (which is the standard POSIX usage) or may be stacked
198       with preceding options (so `-x-' is equivalent to  `-x  --').   Options
199       are not permitted to be stacked after `--' (so `-x-f' is an error), but
200       note the GNU-style option form discussed above,  where  `--shwordsplit'
201       is permitted and does not end option processing.
202
203       Except  when  the sh/ksh emulation single-letter options are in effect,
204       the option `-b' (or `+b') ends option processing.  `-b' is  like  `--',
205       except that further single-letter options can be stacked after the `-b'
206       and will take effect as normal.
207

COMPATIBILITY

209       Zsh tries to emulate sh or ksh when it is invoked as sh or ksh  respec‐
210       tively;  more  precisely,  it  looks at the first letter of the name by
211       which it was invoked, excluding any initial `r' (assumed to  stand  for
212       `restricted'),  and  if  that  is `b', `s' or `k' it will emulate sh or
213       ksh.  Furthermore, if invoked as su (which happens on  certain  systems
214       when  the  shell  is executed by the su command), the shell will try to
215       find an alternative name from the SHELL environment variable  and  per‐
216       form emulation based on that.
217
218       In sh and ksh compatibility modes the following parameters are not spe‐
219       cial and not initialized by the shell:  ARGC,  argv,  cdpath,  fignore,
220       fpath,  HISTCHARS,  mailpath,  MANPATH,  manpath, path, prompt, PROMPT,
221       PROMPT2, PROMPT3, PROMPT4, psvar, status, watch.
222
223       The usual zsh startup/shutdown scripts are not executed.  Login  shells
224       source /etc/profile followed by $HOME/.profile.  If the ENV environment
225       variable is set on  invocation,  $ENV  is  sourced  after  the  profile
226       scripts.  The value of ENV is subjected to parameter expansion, command
227       substitution, and arithmetic expansion before being  interpreted  as  a
228       pathname.   Note  that the PRIVILEGED option also affects the execution
229       of startup files.
230
231       The following options are set if the shell is invoked  as  sh  or  ksh:
232       NO_BAD_PATTERN,    NO_BANG_HIST,    NO_BG_NICE,   NO_EQUALS,   NO_FUNC‐
233       TION_ARGZERO, GLOB_SUBST,  NO_GLOBAL_EXPORT,  NO_HUP,  INTERACTIVE_COM‐
234       MENTS,  KSH_ARRAYS,  NO_MULTIOS, NO_NOMATCH, NO_NOTIFY, POSIX_BUILTINS,
235       NO_PROMPT_PERCENT,    RM_STAR_SILENT,    SH_FILE_EXPANSION,    SH_GLOB,
236       SH_OPTION_LETTERS,   SH_WORD_SPLIT.    Additionally  the  BSD_ECHO  and
237       IGNORE_BRACES options are set if zsh  is  invoked  as  sh.   Also,  the
238       KSH_OPTION_PRINT,  LOCAL_OPTIONS,  PROMPT_BANG,  PROMPT_SUBST  and SIN‐
239       GLE_LINE_ZLE options are set if zsh is invoked as ksh.
240

RESTRICTED SHELL

242       When the basename of the command used to invoke  zsh  starts  with  the
243       letter  `r'  or the `-r' command line option is supplied at invocation,
244       the shell becomes  restricted.   Emulation  mode  is  determined  after
245       stripping  the  letter `r' from the invocation name.  The following are
246       disabled in restricted mode:
247
248       ·      changing directories with the cd builtin
249
250       ·      changing or unsetting the PATH, path, MODULE_PATH,  module_path,
251              SHELL,  HISTFILE,  HISTSIZE,  GID,  EGID,  UID,  EUID, USERNAME,
252              LD_LIBRARY_PATH,    LD_AOUT_LIBRARY_PATH,     LD_PRELOAD     and
253              LD_AOUT_PRELOAD parameters
254
255       ·      specifying command names containing /
256
257       ·      specifying command pathnames using hash
258
259       ·      redirecting output to files
260
261       ·      using the exec builtin command to replace the shell with another
262              command
263
264       ·      using jobs -Z to overwrite the shell process' argument and envi‐
265              ronment space
266
267       ·      using  the ARGV0 parameter to override argv[0] for external com‐
268              mands
269
270       ·      turning off restricted mode with set +r or unsetopt RESTRICTED
271
272       These restrictions are enforced after  processing  the  startup  files.
273       The  startup  files  should set up PATH to point to a directory of com‐
274       mands which can be safely invoked in the restricted environment.   They
275       may also add further restrictions by disabling selected builtins.
276
277       Restricted  mode  can  also  be  activated  any  time  by  setting  the
278       RESTRICTED option.   This  immediately  enables  all  the  restrictions
279       described  above  even if the shell still has not processed all startup
280       files.
281

STARTUP/SHUTDOWN FILES

283       Commands are first read from /etc/zshenv; this  cannot  be  overridden.
284       Subsequent behaviour is modified by the RCS and GLOBAL_RCS options; the
285       former affects all startup files, while the second only affects  global
286       startup  files  (those  shown here with an path starting with a /).  If
287       one of the options is  unset  at  any  point,  any  subsequent  startup
288       file(s)  of the corresponding type will not be read.  It is also possi‐
289       ble for a file in  $ZDOTDIR  to  re-enable  GLOBAL_RCS.  Both  RCS  and
290       GLOBAL_RCS are set by default.
291
292       Commands  are then read from $ZDOTDIR/.zshenv.  If the shell is a login
293       shell, commands are read from /etc/zprofile  and  then  $ZDOTDIR/.zpro‐
294       file.   Then,  if  the  shell  is  interactive,  commands are read from
295       /etc/zshrc and then $ZDOTDIR/.zshrc.  Finally, if the shell is a  login
296       shell, /etc/zlogin and $ZDOTDIR/.zlogin are read.
297
298       When  a  login  shell  exits,  the  files  $ZDOTDIR/.zlogout  and  then
299       /etc/zlogout are read.  This happens with either an explicit  exit  via
300       the exit or logout commands, or an implicit exit by reading end-of-file
301       from the terminal.  However, if the shell terminates  due  to  exec'ing
302       another  process,  the  logout  files  are  not  read.   These are also
303       affected by the RCS and GLOBAL_RCS options.  Note  also  that  the  RCS
304       option  affects  the saving of history files, i.e. if RCS is unset when
305       the shell exits, no history file will be saved.
306
307       If ZDOTDIR is unset, HOME is used instead.  Files listed above as being
308       in /etc may be in another directory, depending on the installation.
309
310       As /etc/zshenv is run for all instances of zsh, it is important that it
311       be kept as small as possible.  In particular, it is a good idea to  put
312       code  that does not need to be run for every single shell behind a test
313       of the form `if [[ -o rcs ]]; then ...' so that it will not be executed
314       when zsh is invoked with the `-f' option.
315
316       Any  of  these files may be pre-compiled with the zcompile builtin com‐
317       mand (see zshbuiltins(1)).  If a compiled file exists  (named  for  the
318       original  file plus the .zwc extension) and it is newer than the origi‐
319       nal file, the compiled file will be used instead.
320
321
322
323ZSHROADMAP(1)               General Commands Manual              ZSHROADMAP(1)
324
325
326

NAME

328       zshroadmap - informal introduction to the zsh manual
329
330       The Zsh Manual, like the shell itself, is large and often  complicated.
331       This section of the manual provides some pointers to areas of the shell
332       that are likely to be of particular interest to new  users,  and  indi‐
333       cates where in the rest of the manual the documentation is to be found.
334

WHEN THE SHELL STARTS

336       When it starts, the shell reads commands from various files.  These can
337       be  created  or  edited  to  customize  the  shell.   See  the  section
338       Startup/Shutdown Files in zsh(1).
339
340       If no personal initialization files exist for the current user, a func‐
341       tion is run to help you change some of the most  common  settings.   It
342       won't appear if your administrator has disabled the zsh/newuser module.
343       The function is designed to be self-explanatory.  You  can  run  it  by
344       hand  with  `autoload -Uz zsh-newuser-install; zsh-newuser-install -f'.
345       See also the section User Configuration Functions in zshcontrib(1).
346

INTERACTIVE USE

348       Interaction with the shell uses the builtin Zsh Line Editor, ZLE.  This
349       is described in detail in zshzle(1).
350
351       The  first  decision a user must make is whether to use the Emacs or Vi
352       editing mode as the  keys  for  editing  are  substantially  different.
353       Emacs  editing  mode  is probably more natural for beginners and can be
354       selected explicitly with the command bindkey -e.
355
356       A history mechanism for retrieving previously typed lines (most  simply
357       with  the  Up or Down arrow keys) is available; note that, unlike other
358       shells, zsh will not save these lines when the shell exits  unless  you
359       set  appropriate variables, and the number of history lines retained by
360       default is quite small (30 lines).  See the description  of  the  shell
361       variables  (referred  to  in the documentation as parameters) HISTFILE,
362       HISTSIZE and SAVEHIST in zshparam(1).
363
364       The shell now supports the UTF-8 character set (and also others if sup‐
365       ported  by  the  operating system).  This is (mostly) handled transpar‐
366       ently by the shell, but the degree of support in terminal emulators  is
367       variable.   There  is  some  discussion  of  this  in  the  shell  FAQ,
368       http://zsh.dotsrc.org/FAQ/ .  Note in  particular  that  for  combining
369       characters  to  be  handled the option COMBINING_CHARS needs to be set.
370       Because the shell is now more sensitive to the definition of the  char‐
371       acter  set, note that if you are upgrading from an older version of the
372       shell you should ensure that the appropriate variable, either LANG  (to
373       affect  all  aspects  of  the shell's operation) or LC_CTYPE (to affect
374       only the handling of character sets) is set to  an  appropriate  value.
375       This  is true even if you are using a single-byte character set includ‐
376       ing extensions of ASCII such as ISO-8859-1  or  ISO-8859-15.   See  the
377       description of LC_CTYPE in zshparam(1).
378
379   Completion
380       Completion  is  a feature present in many shells. It allows the user to
381       type only a part (usually the prefix) of a word and have the shell fill
382       in  the rest.  The completion system in zsh is programmable.  For exam‐
383       ple, the shell can be set to complete email addresses in  arguments  to
384       the  mail command from your ~/.abook/addressbook; usernames, hostnames,
385       and even remote paths in arguments to scp, and so  on.   Anything  that
386       can  be written in or glued together with zsh can be the source of what
387       the line editor offers as possible completions.
388
389       Zsh has two completion systems, an old, so  called  compctl  completion
390       (named  after  the builtin command that serves as its complete and only
391       user interface), and a new one, referred to as  compsys,  organized  as
392       library  of builtin and user-defined functions.  The two systems differ
393       in their interface for specifying the  completion  behavior.   The  new
394       system  is  more customizable and is supplied with completions for many
395       commonly used commands; it is therefore to be preferred.
396
397       The completion system must be enabled explicitly when the shell starts.
398       For more information see zshcompsys(1).
399
400   Extending the line editor
401       Apart from completion, the line editor is highly extensible by means of
402       shell functions.  Some useful functions are provided  with  the  shell;
403       they provide facilities such as:
404
405       insert-composed-char
406              composing characters not found on the keyboard
407
408       match-words-by-style
409              configuring what the line editor considers a word when moving or
410              deleting by word
411
412       history-beginning-search-backward-end, etc.
413              alternative ways of searching the shell history
414
415       replace-string, replace-pattern
416              functions for replacing strings or patterns globally in the com‐
417              mand line
418
419       edit-command-line
420              edit the command line with an external editor.
421
422       See  the  section  `ZLE Functions' in zshcontrib(1) for descriptions of
423       these.
424

OPTIONS

426       The shell has a large number of options  for  changing  its  behaviour.
427       These  cover  all aspects of the shell; browsing the full documentation
428       is the only good way to become acquainted with the many  possibilities.
429       See zshoptions(1).
430

PATTERN MATCHING

432       The  shell  has  a  rich  set  of patterns which are available for file
433       matching (described in the documentation as `filename  generation'  and
434       also  known for historical reasons as `globbing') and for use when pro‐
435       gramming.  These are described in the section `Filename Generation'  in
436       zshexpn(1).
437
438       Of particular interest are the following patterns that are not commonly
439       supported by other systems of pattern matching:
440
441       **     for matching over multiple directories
442
443       ~, ^   the  ability  to  exclude  patterns  from  matching   when   the
444              EXTENDED_GLOB option is set
445
446       (...)  glob  qualifiers, included in parentheses at the end of the pat‐
447              tern, which select  files  by  type  (such  as  directories)  or
448              attribute (such as size).
449

GENERAL COMMENTS ON SYNTAX

451       Although  the  syntax  of zsh is in ways similar to the Korn shell, and
452       therefore more remotely to the original UNIX shell, the  Bourne  shell,
453       its  default  behaviour  does  not entirely correspond to those shells.
454       General shell syntax is introduced in the section  `Shell  Grammar'  in
455       zshmisc(1).
456
457       One  commonly encountered difference is that variables substituted onto
458       the command line are not split into words.  See the description of  the
459       shell option SH_WORD_SPLIT in the section `Parameter Expansion' in zsh‐
460       expn(1).  In zsh, you can either explicitly request the splitting (e.g.
461       ${=foo})  or  use  an  array when you want a variable to expand to more
462       than one word.  See the section `Array Parameters' in zshparam(1).
463

PROGRAMMING

465       The most convenient way of adding enhancements to the  shell  is  typi‐
466       cally  by  writing  a  shell  function  and  arranging  for  it  to  be
467       autoloaded.  Functions are described in the section `Functions' in zsh‐
468       misc(1).   Users  changing  from  the  C shell and its relatives should
469       notice that aliases are less used in zsh as they don't perform argument
470       substitution, only simple text replacement.
471
472       A few general functions, other than those for the line editor described
473       above, are provided with the shell and are described in  zshcontrib(1).
474       Features include:
475
476       promptinit
477              a  prompt theme system for changing prompts easily, see the sec‐
478              tion `Prompt Themes'
479
480
481       zsh-mime-setup
482              a MIME-handling system which dispatches  commands  according  to
483              the suffix of a file as done by graphical file managers
484
485       zcalc  a calculator
486
487       zargs  a version of xargs that makes the find command redundant
488
489       zmv    a command for renaming files by means of shell patterns.
490
491
492
493ZSHALL(1)                   General Commands Manual                  ZSHALL(1)
494
495
496

FILES

498       $ZDOTDIR/.zshenv
499       $ZDOTDIR/.zprofile
500       $ZDOTDIR/.zshrc
501       $ZDOTDIR/.zlogin
502       $ZDOTDIR/.zlogout
503       ${TMPPREFIX}*   (default is /tmp/zsh*)
504       /etc/zshenv
505       /etc/zprofile
506       /etc/zshrc
507       /etc/zlogin
508       /etc/zlogout    (installation-specific - /etc is the default)
509

SEE ALSO

511       sh(1), csh(1), tcsh(1), rc(1), bash(1), ksh(1)
512
513       IEEE  Standard  for  information Technology - Portable Operating System
514       Interface (POSIX) - Part 2: Shell and Utilities, IEEE Inc,  1993,  ISBN
515       1-55937-255-9.
516
517
518
519zsh 5.0.2                      December 21, 2012                     ZSHALL(1)
Impressum