1ZSHALL(1) General Commands Manual ZSHALL(1)
2
6 zshall - the Z shell meta-man page
7
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 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
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
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@sunsite.dk>. 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
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 Primary site
51 ftp://ftp.zsh.org/pub/zsh/
52 http://www.zsh.org/pub/zsh/
53 Australia
55 ftp://ftp.zsh.org/pub/zsh/
56 http://www.zsh.org/pub/zsh/
57 Denmark
59 ftp://sunsite.dk/pub/unix/shells/zsh/
60 Finland
62 ftp://ftp.funet.fi/pub/unix/shells/zsh/
63 Germany
65 ftp://ftp.fu-berlin.de/pub/unix/shells/zsh/ (H)
66 ftp://ftp.gmd.de/packages/zsh/
67 ftp://ftp.uni-trier.de/pub/unix/shell/zsh/
68 Hungary
70 ftp://ftp.cs.elte.hu/pub/zsh/
71 http://www.cs.elte.hu/pub/zsh/
72 ftp://ftp.kfki.hu/pub/packages/zsh/
73 Israel
75 ftp://ftp.math.technion.ac.il/pub/zsh/
76 http://www.math.technion.ac.il/pub/zsh/
77 Japan
79 ftp://ftp.win.ne.jp/pub/shell/zsh/
80 Korea
82 ftp://linux.sarang.net/mirror/system/shell/zsh/
83 Netherlands
85 ftp://ftp.demon.nl/pub/mirrors/zsh/
86 Norway
88 ftp://ftp.uit.no/pub/unix/shells/zsh/
89 Poland
91 ftp://sunsite.icm.edu.pl/pub/unix/shells/zsh/
92 Romania
94 ftp://ftp.roedu.net/pub/mirrors/ftp.zsh.org/pub/zsh/
95 ftp://ftp.kappa.ro/pub/mirrors/ftp.zsh.org/pub/zsh/
96 Slovenia
98 ftp://ftp.siol.net/mirrors/zsh/
99 Sweden
101 ftp://ftp.lysator.liu.se/pub/unix/zsh/
102 UK
104 ftp://ftp.net.lut.ac.uk/zsh/
105 ftp://sunsite.org.uk/packages/zsh/
106 USA
108 http://zsh.open-mirror.com/
109 The up-to-date source code is available via anonymous CVS from Source‐
111 forge. See http://sourceforge.net/projects/zsh/ for details.
112
114 Zsh has 3 mailing lists:
115 <zsh-announce@sunsite.dk>
117 Announcements about releases, major changes in the shell and the
118 monthly posting of the Zsh FAQ. (moderated)
119 <zsh-users@sunsite.dk>
121 User discussions.
122 <zsh-workers@sunsite.dk>
124 Hacking, development, bug reports and patches.
125 To subscribe or unsubscribe, send mail to the associated administrative
127 address for the mailing list.
128 <zsh-announce-subscribe@sunsite.dk>
130 <zsh-users-subscribe@sunsite.dk>
131 <zsh-workers-subscribe@sunsite.dk>
132 <zsh-announce-unsubscribe@sunsite.dk>
133 <zsh-users-unsubscribe@sunsite.dk>
134 <zsh-workers-unsubscribe@sunsite.dk>
135 YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED. All
137 submissions to zsh-announce are automatically forwarded to zsh-users.
138 All submissions to zsh-users are automatically forwarded to zsh-work‐
139 ers.
140 If you have problems subscribing/unsubscribing to any of the mailing
142 lists, send mail to <listmaster@zsh.org>. The mailing lists are main‐
143 tained by Karsten Thygesen <karthy@kom.auc.dk>.
144 The mailing lists are archived; the archives can be accessed via the
146 administrative addresses listed above. There is also a hypertext ar‐
147 chive, maintained by Geoff Wing <gcw@zsh.org>, available at
148 http://www.zsh.org/mla/.
149
151 Zsh has a list of Frequently Asked Questions (FAQ), maintained by Peter
152 Stephenson <pws@zsh.org>. It is regularly posted to the newsgroup
153 comp.unix.shell and the zsh-announce mailing list. The latest version
154 can be found at any of the Zsh FTP sites, or at
155 http://www.zsh.org/FAQ/. The contact address for FAQ-related matters
156 is <faqmaster@zsh.org>.
157
159 Zsh has a web page which is located at http://www.zsh.org/. This is
160 maintained by Karsten Thygesen <karthy@zsh.org>, of SunSITE Denmark.
161 The contact address for web-related matters is <webmaster@zsh.org>.
162
164 A userguide is currently in preparation. It is intended to complement
165 the manual, with explanations and hints on issues where the manual can
166 be cabbalistic, hierographic, or downright mystifying (for example, the
167 word `hierographic' does not exist). It can be viewed in its current
168 state at http://zsh.sunsite.dk/Guide/. At the time of writing, chap‐
169 ters dealing with startup files and their contents and the new comple‐
170 tion system were essentially complete.
171
173 A `wiki' website for zsh has been created at http://www.zshwiki.org/.
174 This is a site which can be added to and modified directly by users
175 without any special permission. You can add your own zsh tips and con‐
176 figurations.
177
179 The following flags are interpreted by the shell when invoked to deter‐
180 mine where the shell will read commands from:
181 -c Take the first argument as a command to execute, rather than
183 reading commands from a script or standard input. If any fur‐
184 ther arguments are given, the first one is assigned to $0,
185 rather than being used as a positional parameter.
186 -i Force shell to be interactive.
188 -s Force shell to read commands from the standard input. If the -s
190 flag is not present and an argument is given, the first argument
191 is taken to be the pathname of a script to execute.
192 After the first one or two arguments have been appropriated as
194 described above, the remaining arguments are assigned to the positional
195 parameters.
196 For further options, which are common to invocation and the set
198 builtin, see zshoptions(1).
199 Options may be specified by name using the -o option. -o acts like a
201 single-letter option, but takes a following string as the option name.
202 For example,
203 zsh -x -o shwordsplit scr
205 runs the script scr, setting the XTRACE option by the corresponding
207 letter `-x' and the SH_WORD_SPLIT option by name. Options may be
208 turned off by name by using +o instead of -o. -o can be stacked up
209 with preceding single-letter options, so for example `-xo shwordsplit'
210 or `-xoshwordsplit' is equivalent to `-x -o shwordsplit'.
211 Options may also be specified by name in GNU long option style,
213 `--option-name'. When this is done, `-' characters in the option name
214 are permitted: they are translated into `_', and thus ignored. So, for
215 example, `zsh --sh-word-split' invokes zsh with the SH_WORD_SPLIT
216 option turned on. Like other option syntaxes, options can be turned
217 off by replacing the initial `-' with a `+'; thus `+-sh-word-split' is
218 equivalent to `--no-sh-word-split'. Unlike other option syntaxes,
219 GNU-style long options cannot be stacked with any other options, so for
220 example `-x-shwordsplit' is an error, rather than being treated like
221 `-x --shwordsplit'.
222 The special GNU-style option `--version' is handled; it sends to stan‐
224 dard output the shell's version information, then exits successfully.
225 `--help' is also handled; it sends to standard output a list of options
226 that can be used when invoking the shell, then exits successfully.
227 Option processing may be finished, allowing following arguments that
229 start with `-' or `+' to be treated as normal arguments, in two ways.
230 Firstly, a lone `-' (or `+') as an argument by itself ends option pro‐
231 cessing. Secondly, a special option `--' (or `+-'), which may be spec‐
232 ified on its own (which is the standard POSIX usage) or may be stacked
233 with preceding options (so `-x-' is equivalent to `-x --'). Options
234 are not permitted to be stacked after `--' (so `-x-f' is an error), but
235 note the GNU-style option form discussed above, where `--shwordsplit'
236 is permitted and does not end option processing.
237 Except when the sh/ksh emulation single-letter options are in effect,
239 the option `-b' (or `+b') ends option processing. `-b' is like `--',
240 except that further single-letter options can be stacked after the `-b'
241 and will take effect as normal.
242
244 Zsh tries to emulate sh or ksh when it is invoked as sh or ksh respec‐
245 tively; more precisely, it looks at the first letter of the name by
246 which it was invoked, excluding any initial `r' (assumed to stand for
247 `restricted'), and if that is `s' or `k' it will emulate sh or ksh.
248 Furthermore, if invoked as su (which happens on certain systems when
249 the shell is executed by the su command), the shell will try to find an
250 alternative name from the SHELL environment variable and perform emula‐
251 tion based on that.
252 In sh and ksh compatibility modes the following parameters are not spe‐
254 cial and not initialized by the shell: ARGC, argv, cdpath, fignore,
255 fpath, HISTCHARS, mailpath, MANPATH, manpath, path, prompt, PROMPT,
256 PROMPT2, PROMPT3, PROMPT4, psvar, status, watch.
257 The usual zsh startup/shutdown scripts are not executed. Login shells
259 source /etc/profile followed by $HOME/.profile. If the ENV environment
260 variable is set on invocation, $ENV is sourced after the profile
261 scripts. The value of ENV is subjected to parameter expansion, command
262 substitution, and arithmetic expansion before being interpreted as a
263 pathname. Note that the PRIVILEGED option also affects the execution
264 of startup files.
265 The following options are set if the shell is invoked as sh or ksh:
267 NO_BAD_PATTERN, NO_BANG_HIST, NO_BG_NICE, NO_EQUALS, NO_FUNC‐
268 TION_ARGZERO, GLOB_SUBST, NO_GLOBAL_EXPORT, NO_HUP, INTERACTIVE_COM‐
269 MENTS, KSH_ARRAYS, NO_MULTIOS, NO_NOMATCH, NO_NOTIFY, POSIX_BUILTINS,
270 NO_PROMPT_PERCENT, RM_STAR_SILENT, SH_FILE_EXPANSION, SH_GLOB,
271 SH_OPTION_LETTERS, SH_WORD_SPLIT. Additionally the BSD_ECHO and
272 IGNORE_BRACES options are set if zsh is invoked as sh. Also, the
273 KSH_OPTION_PRINT, LOCAL_OPTIONS, PROMPT_BANG, PROMPT_SUBST and SIN‐
274 GLE_LINE_ZLE options are set if zsh is invoked as ksh.
275
277 When the basename of the command used to invoke zsh starts with the
278 letter `r' or the `-r' command line option is supplied at invocation,
279 the shell becomes restricted. Emulation mode is determined after
280 stripping the letter `r' from the invocation name. The following are
281 disabled in restricted mode:
282 · changing directories with the cd builtin
284 · changing or unsetting the PATH, path, MODULE_PATH, module_path,
286 SHELL, HISTFILE, HISTSIZE, GID, EGID, UID, EUID, USERNAME,
287 LD_LIBRARY_PATH, LD_AOUT_LIBRARY_PATH, LD_PRELOAD and
288 LD_AOUT_PRELOAD parameters
289 · specifying command names containing /
291 · specifying command pathnames using hash
293 · redirecting output to files
295 · using the exec builtin command to replace the shell with another
297 command
298 · using jobs -Z to overwrite the shell process' argument and envi‐
300 ronment space
301 · using the ARGV0 parameter to override argv[0] for external com‐
303 mands
304 · turning off restricted mode with set +r or unsetopt RESTRICTED
306 These restrictions are enforced after processing the startup files.
308 The startup files should set up PATH to point to a directory of com‐
309 mands which can be safely invoked in the restricted environment. They
310 may also add further restrictions by disabling selected builtins.
311 Restricted mode can also be activated any time by setting the
313 RESTRICTED option. This immediately enables all the restrictions
314 described above even if the shell still has not processed all startup
315 files.
316
318 Commands are first read from /etc/zshenv; this cannot be overridden.
319 Subsequent behaviour is modified by the RCS and GLOBAL_RCS options; the
320 former affects all startup files, while the second only affects global
321 startup files (those shown here with an path starting with a /). If
322 one of the options is unset at any point, any subsequent startup
323 file(s) of the corresponding type will not be read. It is also possi‐
324 ble for a file in $ZDOTDIR to re-enable GLOBAL_RCS. Both RCS and
325 GLOBAL_RCS are set by default.
326 Commands are then read from $ZDOTDIR/.zshenv. If the shell is a login
328 shell, commands are read from /etc/zprofile and then $ZDOTDIR/.zpro‐
329 file. Then, if the shell is interactive, commands are read from
330 /etc/zshrc and then $ZDOTDIR/.zshrc. Finally, if the shell is a login
331 shell, /etc/zlogin and $ZDOTDIR/.zlogin are read.
332 When a login shell exits, the files $ZDOTDIR/.zlogout and then
334 /etc/zlogout are read. This happens with either an explicit exit via
335 the exit or logout commands, or an implicit exit by reading end-of-file
336 from the terminal. However, if the shell terminates due to exec'ing
337 another process, the logout files are not read. These are also
338 affected by the RCS and GLOBAL_RCS options. Note also that the RCS
339 option affects the saving of history files, i.e. if RCS is unset when
340 the shell exits, no history file will be saved.
341 If ZDOTDIR is unset, HOME is used instead. Files listed above as being
343 in /etc may be in another directory, depending on the installation.
344 As /etc/zshenv is run for all instances of zsh, it is important that it
346 be kept as small as possible. In particular, it is a good idea to put
347 code that does not need to be run for every single shell behind a test
348 of the form `if [[ -o rcs ]]; then ...' so that it will not be executed
349 when zsh is invoked with the `-f' option.
350 Any of these files may be pre-compiled with the zcompile builtin com‐
352 mand (see zshbuiltins(1)). If a compiled file exists (named for the
353 original file plus the .zwc extension) and it is newer than the origi‐
354 nal file, the compiled file will be used instead.
355ZSHROADMAP(1) General Commands Manual ZSHROADMAP(1)
359
363 zshroadmap - informal introduction to the zsh manual
364 The Zsh Manual, like the shell itself, is large and often complicated.
366 This section of the manual provides some pointers to areas of the shell
367 that are likely to be of particular interest to new users, and indi‐
368 cates where in the rest of the manual the documentation is to be found.
369
371 When it starts, the shell reads commands from various files. These can
372 be created or edited to customize the shell. See the section
373 Startup/Shutdown Files in zsh(1).
374 If no personal initialization files exist for the current user, a func‐
376 tion is run to help you change some of the most common settings. It
377 won't appear if your administrator has disabled the zsh/newuser module.
378 The function is designed to be self-explanatory. You can run it by
379 hand with `autoload -Uz zsh-newuser-install; zsh-newuser-install -f'.
380 See also the section User Configuration Functions in zshcontrib(1).
381
383 Interaction with the shell uses the builtin Zsh Line Editor, ZLE. This
384 is described in detail in zshzle(1).
385 The first decision a user must make is whether to use the Emacs or Vi
387 editing mode as the keys for editing are substantially different.
388 Emacs editing mode is probably more natural for beginners and can be
389 selected explicitly with the command bindkey -e.
390 A history mechanism for retrieving previously typed lines (most simply
392 with the Up or Down arrow keys) is available; note that, unlike other
393 shells, zsh will not save these lines when the shell exits unless you
394 set appropriate variables, and the number of history lines retained by
395 default is quite small (30 lines). See the description of the shell
396 variables (referred to in the documentation as parameters) HISTFILE,
397 HISTSIZE and SAVEHIST in zshparam(1).
398 The shell now supports the UTF-8 character set (and also others if sup‐
400 ported by the operating system). This is (mostly) handled transpar‐
401 ently by the shell, but the degree of support in terminal emulators is
402 variable. There is some discussion of this in the shell FAQ,
403 http://zsh.dotsrc.org/FAQ/ . Note in particular that for combining
404 characters to be handled the option COMBINING_CHARS needs to be set.
405 Because the shell is now more sensitive to the definition of the char‐
406 acter set, note that if you are upgrading from an older version of the
407 shell you should ensure that the appropriate variable, either LANG (to
408 affect all aspects of the shell's operation) or LC_CTYPE (to affect
409 only the handling of character sets) is set to an appropriate value.
410 This is true even if you are using a single-byte character set includ‐
411 ing extensions of ASCII such as ISO-8859-1 or ISO-8859-15. See the
412 description of LC_CTYPE in zshparam(1).
413 Completion
415 Completion is a feature present in many shells. It allows the user to
416 type only a part (usually the prefix) of a word and have the shell fill
417 in the rest. The completion system in zsh is programmable. For exam‐
418 ple, the shell can be set to complete email addresses in arguments to
419 the mail command from your ~/.abook/addressbook; usernames, hostnames,
420 and even remote paths in arguments to scp, and so on. Anything that
421 can be written in or glued together with zsh can be the source of what
422 the line editor offers as possible completions.
423 Zsh has two completion systems, an old, so called compctl completion
425 (named after the builtin command that serves as its complete and only
426 user interface), and a new one, referred to as compsys, organized as
427 library of builtin and user-defined functions. The two systems differ
428 in their interface for specifying the completion behavior. The new
429 system is more customizable and is supplied with completions for many
430 commonly used commands; it is therefore to be preferred.
431 The completion system must be enabled explicitly when the shell starts.
433 For more information see zshcompsys(1).
434 Extending the line editor
436 Apart from completion, the line editor is highly extensible by means of
437 shell functions. Some useful functions are provided with the shell;
438 they provide facilities such as:
439 insert-composed-char
441 composing characters not found on the keyboard
442 match-words-by-style
444 configuring what the line editor considers a word when moving or
445 deleting by word
446 history-beginning-search-backward-end, etc.
448 alternative ways of searching the shell history
449 replace-string, replace-pattern
451 functions for replacing strings or patterns globally in the com‐
452 mand line
453 edit-command-line
455 edit the command line with an external editor.
456 See the section `ZLE Functions' in zshcontrib(1) for descriptions of
458 these.
459
461 The shell has a large number of options for changing its behaviour.
462 These cover all aspects of the shell; browsing the full documentation
463 is the only good way to become acquainted with the many possibilities.
464 See zshoptions(1).
465
467 The shell has a rich set of patterns which are available for file
468 matching (described in the documentation as `filename generation' and
469 also known for historical reasons as `globbing') and for use when pro‐
470 gramming. These are described in the section `Filename Generation' in
471 zshexpn(1).
472 Of particular interest are the following patterns that are not commonly
474 supported by other systems of pattern matching:
475 ** for matching over multiple directories
477 ~, ^ the ability to exclude patterns from matching when the
479 EXTENDED_GLOB option is set
480 (...) glob qualifiers, included in parentheses at the end of the pat‐
482 tern, which select files by type (such as directories) or
483 attribute (such as size).
484
486 Although the syntax of zsh is in ways similar to the Korn shell, and
487 therefore more remotely to the original UNIX shell, the Bourne shell,
488 its default behaviour does not entirely correspond to those shells.
489 General shell syntax is introduced in the section `Shell Grammar' in
490 zshmisc(1).
491 One commonly encountered difference is that variables substituted onto
493 the command line are not split into words. See the description of the
494 shell option SH_WORD_SPLIT in the section `Parameter Expansion' in zsh‐
495 expn(1). In zsh, you can either explicitly request the splitting (e.g.
496 ${=foo}) or use an array when you want a variable to expand to more
497 than one word. See the section `Array Parameters' in zshparam(1).
498
500 The most convenient way of adding enhancements to the shell is typi‐
501 cally by writing a shell function and arranging for it to be
502 autoloaded. Functions are described in the section `Functions' in zsh‐
503 misc(1). Users changing from the C shell and its relatives should
504 notice that aliases are less used in zsh as they don't perform argument
505 substitution, only simple text replacement.
506 A few general functions, other than those for the line editor described
508 above, are provided with the shell and are described in zshcontrib(1).
509 Features include:
510 promptinit
512 a prompt theme system for changing prompts easily, see the sec‐
513 tion `Prompt Themes'
514 zsh-mime-setup
517 a MIME-handling system which dispatches commands according to
518 the suffix of a file as done by graphical file managers
519 zcalc a calculator
521 zargs a version of xargs that makes the find command redundant
523 zmv a command for renaming files by means of shell patterns.
525ZSHALL(1) General Commands Manual ZSHALL(1)
529
533 $ZDOTDIR/.zshenv
534 $ZDOTDIR/.zprofile
535 $ZDOTDIR/.zshrc
536 $ZDOTDIR/.zlogin
537 $ZDOTDIR/.zlogout
538 ${TMPPREFIX}* (default is /tmp/zsh*)
539 /etc/zshenv
540 /etc/zprofile
541 /etc/zshrc
542 /etc/zlogin
543 /etc/zlogout (installation-specific - /etc is the default)
544
546 sh(1), csh(1), tcsh(1), rc(1), bash(1), ksh(1)
547 IEEE Standard for information Technology - Portable Operating System
549 Interface (POSIX) - Part 2: Shell and Utilities, IEEE Inc, 1993, ISBN
550 1-55937-255-9.
551zsh 4.3.10 June 1, 2009 ZSHALL(1)