1 mailto(pws@pwstephenson.fsnet.co.uk)\
2 whentxt(notableofcontents())\
3 COMMENT(-- mytt is like tt but adds quotes `like this' for plain text --)\
10 COMMENT(-- mybf/em are like bf/em but add *emphasis* for text too --)\
23 COMMENT(-- mydit is like dit but no `o' for text mode --)\
31 COMMENT(-- myeit is like eit but fancier text formatting --)\
33 whenlatex(eit())whenhtml(eit())whenman(eit())whenms(eit())whensgml(eit())\
34 whentxt(eit()CHAR(41)))\
36 whenlatex(eit())whenhtml(eit())whenman(eit())whenms(eit())whensgml(eit())\
38 COMMENT(-- don't want headers for text, USENET headers must come first --)\
40 whentxt(report()()())\
41 whenhtml(report(ARG1)(ARG2)(ARG3))\
42 whenlatex(report(ARG1)(ARG2)(ARG3))\
43 whenman(report(ARG1)(ARG2)(ARG3))\
44 whenms(report(ARG1)(ARG2)(ARG3))\
45 whensgml(report(ARG1)(ARG2)(ARG3)))
46 myreport(Z-Shell Frequently-Asked Questions)(Peter Stephenson)(2005/12/14)
47 COMMENT(-- the following are for Usenet and must appear first)\
49 mydit(Archive-Name:) unix-faq/shell/zsh
50 mydit(Last-Modified:) 2005/12/14
51 mydit(Submitted-By:) email(pws@pwstephenson.fsnet.co.uk (Peter Stephenson))
52 mydit(Posting-Frequency:) Monthly
53 mydit(Copyright:) (C) P.W. Stephenson, 1995--2005 (see end of document)
56 This document contains a list of frequently-asked (or otherwise
57 significant) questions concerning the Z-shell, a command interpreter
58 for many UNIX systems which is freely available to anyone with FTP
59 access. Zsh is among the most powerful freely available Bourne-like
60 shell for interactive use.
62 If you have never heard of mytt(sh), mytt(csh) or mytt(ksh), then you are
63 probably better off to start by reading a general introduction to UNIX
64 rather than this document.
66 If you just want to know how to get your hands on the latest version,
67 skip to question link(1.6)(16); if you want to know what to do with
68 insoluble problems, go to link(5.2)(52).
70 whentxt(Notation: Quotes `like this' are ordinary textual quotation
71 marks. Other uses of quotation marks are input to the shell.)
73 COMMENT(-- need to do this specially in text since it should go here --)
75 Chapter 1: Introducing zsh and how to install it
76 1.1. Sources of information
78 1.3. What is it good at?
79 1.4. On what machines will it run? (Plus important compilation notes)
80 1.5. What's the latest version?
81 1.6. Where do I get it?
82 1.7. I don't have root access: how do I make zsh my login shell?
84 Chapter 2: How does zsh differ from...?
87 2.3. Why do my csh aliases not work? (Plus other alias pitfalls.)
90 2.6. Shouldn't zsh be more/less like ksh/(t)csh?
91 2.7. What is zsh's support for Unicode/UTF-8?
93 Chapter 3: How to get various things to work
94 3.1. Why does `$var' where `var="foo bar"' not do what I expect?
95 3.2. In which startup file do I put...?
96 3.3. What is the difference between `export' and the ALL_EXPORT option?
97 3.4. How do I turn off spelling correction/globbing for a single command?
98 3.5. How do I get the Meta key to work on my xterm?
99 3.6. How do I automatically display the directory in my xterm title bar?
100 3.7. How do I make the completion list use eight bit characters?
101 3.8. Why do the cursor (arrow) keys not work?
102 3.9. Why does my terminal act funny in some way?
103 3.10. Why does zsh not work in an Emacs shell mode any more?
104 3.11. Why do my autoloaded functions not autoload [the first time]?
105 3.12. How does base arithmetic work?
106 3.13. How do I get a newline in my prompt?
107 3.14. Why does `bindkey ^a command-name' or 'stty intr ^-' do something funny?
108 3.15. Why can't I bind \C-s and \C-q any more?
109 3.16. How do I execute command `foo' within function `foo'?
110 3.17. Why do history substitutions with single bangs do something funny?
111 3.18. Why does zsh kill off all my background jobs when I logout?
112 3.19. How do I list all my history entries?
113 3.20. How does the alternative loop syntax, e.g. mytt(while {...} {...}) work?
114 3.21. Why is my history not being saved?
115 3.22. How do I get a variable's value to be evaluated as another variable?
116 3.23. How do I prevent the prompt overwriting output when there is no newline?
117 3.24. What's wrong with cut and paste on my xterm?
118 3.25. How do I get coloured prompts on my colour xterm?
119 3.26. Why is my output duplicated with `tt(foo 2>&1 >foo.out | bar)'?
121 Chapter 4: The mysteries of completion
122 4.1. What is completion?
123 4.2. What sorts of things can be completed?
124 4.3. How does zsh deal with ambiguous completions?
125 4.4. How do I complete in the middle of words / just what's before the cursor?
126 4.5. How do I get started with programmable completion?
127 4.6. Suppose I want to complete all files during a special completion?
129 Chapter 5: Multibyte input and output
131 5.1. What is multibyte input?
132 5.2. How does zsh handle multibyte input and output?
133 5.3. How do I ensure multibyte input and output work on my system?
134 5.4. How can I input characters that aren't on my keyboard?
136 Chapter 6: The future of zsh
137 6.1. What bugs are currently known and unfixed? (Plus recent important changes)
138 6.2. Where do I report bugs, get more info / who's working on zsh?
139 6.3. What's on the wish-list?
140 6.4. Did zsh have problems in the year 2000?
145 --- End of Contents ---
148 chapter(Introducing zsh and how to install it)
150 sect(Sources of information)
153 Information on zsh is available via the World Wide Web. The URL
154 is url(http://sunsite.dk/zsh/)(http://sunsite.dk/zsh/) .
155 The server provides this FAQ and much else and is
156 now maintained by Karsten Thygesen and others (mail \
157 email(zsh@sunsite.dk)
158 with any related messages). The FAQ is at \
159 url(http://sunsite.dk/zsh/FAQ/)(http://sunsite.dk/zsh/FAQ/) .
160 The site also contains some contributed zsh scripts and functions;
161 we are delighted to add more, or simply links to your own collection.
163 This document was originally written in YODL, allowing it to be converted
164 easily into various other formats. The master source file lives at
165 url(http://sunsite.dk/zsh/FAQ/zshfaq.yo)
166 (http://sunsite.dk/zsh/FAQ/zshfaq.yo) and the plain text version
167 can be found at url(http://sunsite.dk/zsh/FAQ/zshfaq.txt)
168 (http://sunsite.dk/zsh/FAQ/zshfaq.txt) .
170 Another useful source of information is the collection of FAQ articles
171 posted frequently to the Usenet news groups comp.unix.questions,
172 comp.unix.shells and comp.answers with answers to general questions
173 about UNIX. The fifth of the seven articles deals with shells,
174 including zsh, with a brief description of differences. There is
175 also a separate FAQ on shell differences and how to change your
176 shell. Usenet FAQs are available via FTP from rtfm.mit.edu and
177 mirrors and also on the World Wide Web; see
179 mydit(USA) url(http://www.cis.ohio-state.edu/hypertext/faq/usenet/top.html)
180 (http://www.cis.ohio-state.edu/hypertext/faq/usenet/top.html)
181 mydit(UK) url(http://www.lib.ox.ac.uk/internet/news/faq/comp.unix.shell.html)
182 (http://www.lib.ox.ac.uk/internet/news/faq/comp.unix.shell.html)
183 mydit(Netherlands) url(http://www.cs.uu.nl/wais/html/na-dir/unix-faq/shell/.html)
184 (http://www.cs.uu.nl/wais/html/na-dir/unix-faq/shell/.html)
187 You can also get it via email by emailing \
188 email(mail-server@rtfm.mit.edu)
189 with, in the body of the message, mytt(send faqs/unix-faq/shell/zsh).
191 The latest version of this FAQ is also available directly from any
192 of the zsh archive sites listed in question link(1.6)(16).
194 I have put together a user guide to complement the manual by
195 explaining the most useful features of zsh in a more easy to read way.
196 This can be found at the zsh web site:
197 url(http://zsh.sunsite.dk/Guide/)(http://zsh.sunsite.dk/Guide/)
199 (As a method of reading the following in Emacs, you can type tt(\M-2
200 \C-x $) to make all the indented text vanish, then tt(\M-0 \C-x $)
201 when you are on the title you want.)
203 For any more eclectic information, you should contact the mailing
204 list: see question link(5.2)(52).
209 Zsh is a UNIX command interpreter (shell) which of the standard
210 shells most resembles the Korn shell (ksh); its compatibility with
211 the 1988 Korn shell has been gradually increasing. It includes
212 enhancements of many types, notably in the command-line editor,
213 options for customising its behaviour, filename globbing, features
214 to make C-shell (csh) users feel more at home and extra features
215 drawn from tcsh (another `custom' shell).
217 It was written by Paul Falstad when a student at Princeton; however,
218 Paul doesn't maintain it any more and enquiries should be sent to
219 the mailing list (see question link(5.2)(52)). Zsh is distributed under a
220 standard Berkeley style copyright.
222 For more information, the files Doc/intro.txt or Doc/intro.troff
223 included with the source distribution are highly recommended. A list
224 of features is given in FEATURES, also with the source.
227 sect(What is it good at?)
229 Here are some things that zsh is particularly good at. No claim of
230 exclusivity is made, especially as shells copy one another, though
231 in the areas of command line editing and globbing zsh is well ahead
232 of the competition. I am not aware of a major interactive feature
233 in any other freely-available shell which zsh does not also have
237 it() Command line editing:
239 it() programmable completion: incorporates the ability to use the
240 full power of zsh's globbing and shell programming features,
241 it() multi-line commands editable as a single buffer (even files!),
242 it() variable editing (vared),
243 it() command buffer stack,
244 it() print text straight into the buffer for immediate editing (print -z),
245 it() execution of unbound commands,
246 it() menu completion in two flavours,
247 it() variable, editing function and option name completion,
248 it() inline expansion of variables and history commands.
250 it() Globbing --- extremely powerful, including:
252 it() recursive globbing (cf. find),
253 it() file attribute qualifiers (size, type, etc. also cf. find),
254 it() full alternation and negation of patterns.
256 it() Handling of multiple redirections (simpler than tee).
257 it() Large number of options for tailoring.
258 it() Path expansion (=foo -> /usr/bin/foo).
259 it() Adaptable messages for spelling, watch, time as well as prompt
260 (including conditional expressions).
261 it() Named directories.
262 it() Comprehensive integer and floating point arithmetic.
263 it() Manipulation of arrays (including reverse subscripting).
264 it() Associative arrays (key-to-value hashes)
265 it() Spelling correction.
269 sect(On what machines will it run?)
271 From version 3.0, zsh uses GNU autoconf as the installation
272 mechanism. This considerably increases flexibility over the old
273 `buildzsh' mechanism. Consequently, zsh should compile and run on
274 any modern version of UNIX, and a great many not-so-modern versions
275 too. The file MACHINES in the distribution has more details.
277 There used to be separate ports for Windows and OS/2, but these
278 are rather out of date and hard to get; however, zsh exists for
279 the Cygwin environment. See further notes below.
281 If you need to change something to support a new machine, it would be
282 appreciated if you could add any necessary preprocessor code and
283 alter configure.in and acconfig.h to configure zsh automatically,
284 then send the required context diffs to the list (see question
285 link(5.2)(52)). Please make sure you have the latest version first.
287 To get it to work, retrieve the source distribution (see question
288 link(1.6)(16)), un-gzip it, un-tar it and read the INSTALL file in the top
289 directory. Also read the MACHINES file for up-to-date
290 information on compilation on certain architectures.
292 mybf(Note for users of nawk) (The following information comes from Zoltan
293 Hidvegi): On some systems nawk is broken and produces an incorrect
294 signames.h file. This makes the signals code unusable. This often happens
295 on Ultrix, HP-UX, IRIX (?). Install gawk if you experience such problems.
298 sect(What's the latest version?)
300 Zsh 4.2.7 is the latest production version. The latest development
301 version is 4.3.9; this contains support for multibyte character strings
302 (such as UTF-8 locales). All the main features for multibyte
303 support are now in place, although there is some debugging work
306 There will not be any further 4.0 releases now that 4.2 has become
309 A beta of the next version is sometimes available. Development of zsh is
310 patch by patch, with each intermediate version publicly available. Note
311 that this `open' development system does mean bugs are sometimes
312 introduced into the most recent archived version. These are usually
313 fixed quickly. If you are really interested in getting the latest
314 improvements, and less worried about providing a stable environment,
315 development versions are uploaded quite frequently to the archive in the
316 tt(development) subdirectory.
318 Note also that as the shell changes, it may become incompatible with
319 older versions; see the end of question link(5.1)(51) for a partial list.
320 Changes of this kind are almost always forced by an awkward or
321 unnecessary feature in the original design (as perceived by current
322 users), or to enhance compatibility with other Bourne shell
323 derivatives, or (mostly in the 3.0 series) to provide POSIX compliancy.
326 sect(Where do I get it?)
329 The coordinator of development is currently me; the alias
330 email(coordinator@zsh.org) can be used to contact whoever is in the hot
331 seat. The following are known mirrors (kept frequently up to date); the
332 first is the official archive site, currently in Australia. All are
333 available by anonymous FTP. The major sites keep test versions in the
334 `testing' subdirectory: such up-to-the-minute development versions should
335 only be retrieved if you actually plan to help test the latest version of
336 the shell. The following list also appears on the WWW at
337 url(http://www.zsh.org/)(http://www.zsh.org/) .
340 mydit(Home site) url(ftp://ftp.zsh.org/)(ftp://ftp.zsh.org/)
341 mydit() (also url(http://www.zsh.org/pub/zsh/)
342 (http://www.zsh.org/pub/zsh/))
343 mydit(Denmark) url(ftp://mirrors.dotsrc.org/zsh/)
344 (ftp://mirrors.dotsrc.org/zsh/)
345 mydit() (also url(http://mirrors.dotsrc.org/zsh/)
346 (http://mirrors.dotsrc.org/zsh/))
347 mydit(Finland) url(ftp://ftp.funet.fi/pub/unix/shells/zsh/)
348 (ftp://ftp.funet.fi/pub/unix/shells/zsh/)
349 mydit(France) url(ftp://nephtys.lip6.fr/pub/unix/shells/zsh/)
350 (ftp://nephtys.lip6.fr/pub/unix/shells/zsh/)
351 mydit(Germany) url(ftp://ftp.fu-berlin.de/pub/unix/shells/zsh/)
352 (ftp://ftp.fu-berlin.de/pub/unix/shells/zsh/)
353 mydit(Hungary) url(ftp://ftp.cs.elte.hu/pub/zsh/)
354 (ftp://ftp.cs.elte.hu/pub/zsh/)
355 mydit() (also url(http://www.cs.elte.hu/pub/zsh/)
356 (http://www.cs.elte.hu/pub/zsh/))
357 mydit() url(ftp://ftp.kfki.hu/pub/packages/zsh/)
358 (ftp://ftp.kfki.hu/pub/packages/zsh/)
359 mydit(Israel) url(ftp://ftp.math.technion.ac.il/pub/zsh/)
360 (ftp://ftp.math.technion.ac.il/pub/zsh/)
361 mydit() (also url(http://www.math.technion.ac.il/pub/zsh/)
362 (http://www.math.technion.ac.il/pub/zsh/))
363 mydit(Netherlands) url(ftp://ftp.demon.nl/pub/mirrors/zsh/)
364 (ftp://ftp.demon.nl/pub/mirrors/zsh/)
365 mydit(Poland) url(ftp://sunsite.icm.edu.pl/pub/unix/shells/zsh/)
366 (ftp://sunsite.icm.edu.pl/pub/unix/shells/zsh/)
367 mydit(Romania) url(ftp://ftp.kappa.ro/pub/mirrors/ftp.zsh.org/pub/zsh/)
368 (ftp://ftp.kappa.ro/pub/mirrors/ftp.zsh.org/pub/zsh/)
369 mydit(Sweden) url(ftp://ftp.lysator.liu.se/pub/unix/zsh/)
370 (ftp://ftp.lysator.liu.se/pub/unix/zsh/)
371 mydit(UK) url(ftp://sunsite.org.uk/packages/zsh/)
372 (ftp://sunsite.org.uk/packages/zsh/)
373 mydit(USA) url(http://zsh.open-mirror.com/)
374 (http://zsh.open-mirror.com/)
377 A Windows port used to be maintaiend by Amol Deshpandem based on 3.0.5,
378 but this is rather out of date and hard to find. Various other
379 attempts have been made to port zsh to Windows but I am not aware
380 of any current native Windows version. All recent releases of zsh
381 compile under Cygwin, a freely available UNIX-style environment for the
382 Win32 API, and a pre-compiled version of zsh can be downloaded by
383 the Cygwin installer. You can find information about this at
384 url(http://www.cygwin.com/)(http://www.cygwin.com/). Please email
385 email(zsh-workers@sunsite.dk) if you have information about other ports.
387 Starting from mid-October 1997, there is an archive of patches sent
388 to the maintainers' mailing list. Note that these may not all be
389 added to the shell, and some may already have been; you simply have
390 to search for something you might want which is not in the version
391 you have. Also, there may be some prerequisites earlier in the
392 archive. It can be found on the zsh WWW pages (as described in
396 mydit() url(http://sunsite.dk/zsh/Patches/)
397 (http://sunsite.dk/zsh/Patches/)
400 sect(I don't have root access: how do I make zsh my login shell?)
402 Unfortunately, on many machines you can't use mytt(chsh) to change your
403 shell unless the name of the shell is contained in /etc/shells, so if
404 you have your own copy of zsh you need some sleight-of-hand to use it
405 when you log on. (Simply typing mytt(zsh) is not really a solution since
406 you still have your original login shell waiting for when you exit.)
408 The basic idea is to use mytt(exec <zsh-path>) to replace the current
409 shell with zsh. Often you can do this in a login file such as .profile
410 (if your shell is sh or ksh) or .login (if it's csh). Make sure you
411 have some way of altering the file (e.g. via FTP) before you try this as
412 mytt(exec) is often rather unforgiving.
414 If you have zsh in a subdirectory mytt(bin) of your home directory,
415 put this in .profile:
417 [ -f $HOME/bin/zsh ] && exec $HOME/bin/zsh -l
419 or if your login shell is csh or tcsh, put this in .login:
421 if ( -f ~/bin/zsh ) exec ~/bin/zsh -l
423 (in each case the mytt(-l) tells zsh it is a login shell).
425 If you want to check this works before committing yourself to it,
426 you can make the login shell ask whether to exec zsh. The following
427 work for Bourne-like shells:
429 [ -f $HOME/bin/zsh ] && {
430 echo "Type Y to run zsh: \c"
432 [ "$line" = Y ] && exec $HOME/bin/zsh -l
435 and for C-shell-like shells:
437 if ( -f ~/bin/zsh ) then
438 echo -n "Type Y to run zsh: "
439 if ( "$<" == Y ) exec ~/bin/zsh -l
443 It's not a good idea to put this (even without the -l) into .cshrc,
444 at least without some tests on what the csh is supposed to be doing,
445 as that will cause _every_ instance of csh to turn into a zsh and
446 will cause csh scripts (yes, unfortunately some people write these)
447 which do not call `csh -f' to fail. If you want to tell xterm to
448 run zsh, change the SHELL environment variable to the full path of
449 zsh at the same time as you exec zsh (in fact, this is sensible for
450 consistency even if you aren't using xterm). If you have to exec
451 zsh from your .cshrc, a minimum safety check is mytt(if ($?prompt) exec
454 If you like your login shell to appear in the process list as mytt(-zsh),
455 you can link mytt(zsh) to mytt(-zsh) (e.g. by mytt(ln -s ~/bin/zsh
456 ~/bin/-zsh)) and change the exec to mytt(exec -zsh). (Make sure
457 mytt(-zsh) is in your path.) This has the same effect as the mytt(-l)
460 Footnote: if you DO have root access, make sure zsh goes in
461 /etc/shells on all appropriate machines, including NIS clients, or you
462 may have problems with FTP to that machine.
465 chapter(How does zsh differ from...?)
467 As has already been mentioned, zsh is most similar to ksh, while many
468 of the additions are to please csh users. Here are some more detailed
469 notes. See also the article `UNIX shell differences and how to change
470 your shell' posted frequently to the USENET group comp.unix.shell.
472 sect(Differences from sh and ksh)
475 Most features of ksh (and hence also of sh) are implemented in zsh;
476 problems can arise because the implementation is slightly different.
477 Note also that not all ksh's are the same either. I have based this
478 on the 11/16/88f version of ksh; differences from ksh93 will be more
481 As a summary of the status:
483 myeit() because of all the options it is not safe to assume a general
484 zsh run by a user will behave as if sh or ksh compatible;
485 myeit() invoking zsh as sh or ksh (or if either is a symbolic link to
486 zsh) sets appropriate options and improves compatibility (from
487 within zsh itself, calling mytt(ARGV0=sh zsh) will also work);
488 myeit() from version 3.0 onward the degree of compatibility with sh
489 under these circumstances is very high: zsh can now be used
490 with GNU configure or perl's Configure, for example;
491 myeit() the degree of compatibility with ksh is also high, but a few
492 things are missing: for example the more sophisticated
493 pattern-matching expressions are different for versions before
494 3.1.3 --- see the detailed list below;
495 myeit() also from 3.0, the command `emulate' is available: `emulate
496 ksh' and `emulate sh' set various options as well as changing the
497 effect of single-letter option flags as if the shell had been
498 invoked with the appropriate name. Including the command
499 `emulate sh; setopt localoptions' in a shell function will
500 turn on sh emulation for that function only. In version 4 (and in
501 3.0.6 through 8), this can be abbreviated as `emulate -L sh'.
504 The classic difference is word splitting, discussed in question \
506 this catches out very many beginning zsh users. As explained there,
507 this is actually a bug in every other shell. The answer is to set
508 tt(SH_WORD_SPLIT) for backward compatibility. The next most classic
509 difference is that unmatched glob patterns cause the command to abort;
510 set tt(NO_NOMATCH) for those.
512 Here is a list of various options which will increase ksh
513 compatibility, though maybe decrease zsh's abilities: see the manual
514 entries for tt(GLOB_SUBST), tt(IGNORE_BRACES) (though brace expansion occurs
515 in some versions of ksh), tt(KSH_ARRAYS), tt(KSH_GLOB), tt(KSH_OPTION_PRINT),
516 tt(LOCAL_OPTIONS), tt(NO_BAD_PATTERN), tt(NO_BANG_HIST), tt(NO_EQUALS), \
518 tt(NO_NOMATCH), tt(NO_RCS), tt(NO_SHORT_LOOPS), tt(PROMPT_SUBST), \
520 tt(POSIX_ALIASES), tt(POSIX_BUILTINS), tt(POSIX_IDENTIFIERS),
521 tt(SH_FILE_EXPANSION), tt(SH_GLOB), tt(SH_OPTION_LETTERS),
522 tt(SH_WORD_SPLIT) (see question link(3.1)(31)) and tt(SINGLE_LINE_ZLE).
523 Note that you can also disable any built-in commands which get in
524 your way. If invoked as `ksh', the shell will try to set suitable
527 Here are some differences from ksh which might prove significant for
528 ksh programmers, some of which may be interpreted as bugs; there
529 must be more. Note that this list is deliberately rather full and
530 that most of the items are fairly minor. Those marked `*' perform
531 in a ksh-like manner if the shell is invoked with the name `ksh', or
532 if `emulate ksh' is in effect. Capitalised words with underlines
533 refer to shell options.
538 it()* Shell word splitting: see question link(3.1)(31).
539 it()* Arrays are (by default) more csh-like than ksh-like:
540 subscripts start at 1, not 0; tt(array[0]) refers to tt(array[1]);
541 mytt($array) refers to the whole array, not tt($array[0]);
542 braces are unnecessary: tt($a[1] == ${a[1]}), etc.
543 Set the tt(KSH_ARRAYS) option for compatibility.
544 it() Furthermore, individual elements of arrays in zsh are always
545 strings, not separate parameters. This means, for example, you
546 can't `unset' an array element in zsh as you can in ksh; you
547 can only set it to the empty string, or shorten the array.
548 (You can unset elements of associative arrays in zsh because
549 those are a completely different type of object.)
550 it() Coprocesses are established by mytt(coproc); mytt(|&) behaves like
551 csh. Handling of coprocess file descriptors is also different.
552 it() In mytt(cmd1 && cmd2 &), only mytt(cmd2) instead of the whole
553 expression is run in the background in zsh. The manual implies
554 this is a bug. Use mytt({ cmd1 && cmd2 } &) as a workaround.
556 it() Command line substitutions, globbing etc.:
558 it()* Failure to match a globbing pattern causes an error (use
560 it()* The results of parameter substitutions are treated as plain text:
561 mytt(foo="*"; print $foo) prints all files in ksh but mytt(*) in zsh
562 (use tt(GLOB_SUBST)).
563 it()* tt($PSn) do not do parameter substitution by default (use \
565 it()* Standard globbing does not allow ksh-style `pattern-lists'.
568 ----------------------------------------------------------------------
570 ------ ------ ---------
571 !(foo) ^foo Anything but foo.
572 or foo1~foo2 Anything matching foo1 but foo2[1].
573 @(foo1|foo2|...) (foo1|foo2|...) One of foo1 or foo2 or ...
574 ?(foo) (foo|) Zero or one occurrences of foo.
575 *(foo) (foo)# Zero or more occurrences of foo.
576 +(foo) (foo)## One or more occurrences of foo.
577 ----------------------------------------------------------------------
579 The mytt(^), mytt(~) and mytt(#) (but not mytt(|))forms require \
581 From version 3.1.3, the ksh forms are fully supported when the
582 option tt(KSH_GLOB) is in effect; for previous versions you
583 must use the table above.
585 [1] Note that mytt(~) is the only globbing operator to have a lower
586 precedence than mytt(/). For example, mytt(**/foo~*bar*) matches any
587 file in a subdirectory called mytt(foo), except where mytt(bar)
588 occurred somewhere in the path (e.g. mytt(users/barstaff/foo) will
589 be excluded by the mytt(~) operator). As the mytt(**) operator cannot
590 be grouped (inside parentheses it is treated as mytt(*)), this is
591 the way to exclude some subdirectories from matching a mytt(**).
592 it() Unquoted assignments do file expansion after mytt(:)s (intended for
594 it() mytt(typeset) and mytt(integer) have special behaviour for
595 assignments in ksh, but not in zsh. For example, this doesn't
598 integer k=$(wc -l ~/.zshrc)
600 because the return value from tt(wc) includes leading
601 whitespace which causes wordsplitting. Ksh handles the
602 assignment specially as a single word.
604 it() Command execution:
606 it()* There is no tt($ENV) variable (use tt(/etc/zshrc), tt(~/.zshrc);
607 note also tt($ZDOTDIR)).
608 it() tt($PATH) is not searched for commands specified
609 at invocation without -c.
611 it() Aliases and functions:
613 it() The order in which aliases and functions are defined is significant:
614 function definitions with () expand aliases -- see question \
616 it() Aliases and functions cannot be exported.
617 it() There are no tracked aliases: command hashing replaces these.
618 it() The use of aliases for key bindings is replaced by `bindkey'.
619 it()* Options are not local to functions (use LOCAL_OPTIONS; note this
620 may always be unset locally to propagate options settings from a
621 function to the calling level).
622 it() Functions defined with `function funcname { body }' behave the
623 same way as those defined with `funcname () { body }'. In ksh,
624 the former behave as if the body were read from a file with `.',
625 and only the latter behave as true functions.
627 it() Traps and signals:
629 it()* Traps are not local to functions. The option LOCAL_TRAPS is
630 available from 3.1.6.
631 it() TRAPERR has become TRAPZERR (this was forced by UNICOS which
636 it() The options tt(gmacs), tt(viraw) are not supported.
637 Use bindkey to change the editing behaviour: mytt(set -o {emacs,vi})
638 becomes `bindkey -{e,v}', although `set -o emacs' and `set -o vi'
639 are supported for compatibility; for gmacs, go to emacs mode and
640 use `bindkey \^t gosmacs-transpose-characters'.
641 it() The mytt(keyword) option does not exist and mytt(-k) is instead
642 interactivecomments. (mytt(keyword) is not in recent versions
644 it()* Management of histories in multiple shells is different:
645 the history list is not saved and restored after each command.
646 The option tt(SHARE_HISTORY) appeared in 3.1.6 and is set in ksh
647 compatibility mode to remedy this.
648 it() mytt(\) does not escape editing chars (use mytt(^V)).
649 it() Not all ksh bindings are set (e.g. mytt(<ESC>#); try mytt(<ESC>q)).
650 it()* mytt(#) in an interactive shell is not treated as a comment by
652 it() In vi command mode the keys "k" and "j" move the cursor to the
653 end of the line. To move the cursor to the start instead, use
655 bindkey -M vicmd 'k' vi-up-line-or-history
656 bindkey -M vicmd 'j' vi-down-line-or-history
659 it() Built-in commands:
661 it() Some built-ins (tt(r), tt(autoload), tt(history), tt(integer) ...)
663 it() There is no built-in command newgrp: use e.g. mytt(alias
664 newgrp="exec newgrp")
665 it() mytt(jobs) has no mytt(-n) flag.
667 it() Other idiosyncrasies:
669 it() mytt(select) always redisplays the list of selections on each loop.
674 sect(Similarities with csh)
676 Although certain features aim to ease the withdrawal symptoms of csh
677 (ab)users, the syntax is in general rather different and you should
678 certainly not try to run scripts without modification. The c2z script
679 is provided with the source (in Misc/c2z) to help convert .cshrc
680 and .login files; see also the next question concerning aliases,
681 particularly those with arguments.
683 Csh-compatibility additions include:
685 it() tt(logout), tt(rehash), tt(source), tt((un)limit) built-in commands.
686 it() tt(*rc) file for interactive shells.
687 it() Directory stacks.
688 it() tt(cshjunkie*), tt(ignoreeof) options.
689 it() The tt(CSH_NULL_GLOB) option.
690 it() tt(>&), tt(|&) etc. redirection.
691 (Note that mytt(>file 2>&1) is the standard Bourne shell command for
693 it() tt(foreach ...) loops; alternative syntax for other loops.
694 it() Alternative syntax mytt(if ( ... ) ...), though this still doesn't
695 work like csh: it expects a command in the parentheses. Also
696 mytt(for), mytt(which).
697 it() tt($PROMPT) as well as tt($PS1), tt($status) as well as tt($?),
698 tt($#argv) as well as tt($#), ....
699 it() Escape sequences via tt(%) for prompts.
700 it() Special array variables tt($PATH) etc. are colon-separated, tt($path)
702 it() tt(!)-type history (which may be turned off via mytt(setopt
704 it() Arrays have csh-like features (see under link(2.1)(21)).
708 sect(Why do my csh aliases not work? (Plus other alias pitfalls.))
711 First of all, check you are using the syntax
713 alias newcmd='list of commands'
717 alias newcmd 'list of commands'
719 which won't work. (It tells you if `newcmd' and `list of commands' are
720 already defined as aliases.)
722 Otherwise, your aliases probably contain references to the command
723 line of the form mytt(\!*), etc. Zsh does not handle this behaviour as it
724 has shell functions which provide a way of solving this problem more
725 consistent with other forms of argument handling. For example, the
728 alias cd 'cd \!*; echo $cwd'
730 can be replaced by the zsh function,
732 cd() { builtin cd "$@"; echo $PWD; }
734 (the `builtin' tells zsh to use its own `cd', avoiding an infinite loop)
737 cd() { builtin cd "$@"; print -D $PWD; }
739 (which converts your home directory to a tt(~)). In fact, this problem is
740 better solved by defining the special function chpwd() (see the manual).
741 Note also that the mytt(;) at the end of the function is optional in zsh,
742 but not in ksh or sh (for sh's where it exists).
744 Here is Bart Schaefer's guide to converting csh aliases for zsh.
747 myeit() If the csh alias references "parameters" (tt(\!:1), tt(\!*) etc.),
748 then in zsh you need a function (referencing tt($1), tt($*) etc.).
749 Otherwise, you can use a zsh alias.
751 myeit() If you use a zsh function, you need to refer _at_least_ to
752 tt($*) in the body (inside the tt({ })). Parameters don't magically
753 appear inside the tt({ }) the way they get appended to an alias.
755 myeit() If the csh alias references its own name (tt(alias rm "rm -i")),
756 then in a zsh function you need the "command" keyword
757 (function tt(rm() { command rm -i "$@" })), but in a zsh alias
758 you don't (tt(alias rm="rm -i")).
760 myeit() If you have aliases that refer to each other (tt(alias ls "ls -C";
761 alias lf "ls -F" ==> lf == ls -C -F)) then you must either:
763 it() convert all of them to zsh functions; or
764 it() after converting, be sure your .zshrc defines all of your
765 aliases before it defines any of your functions.
768 Those first four are all you really need, but here are four more for
769 heavy csh alias junkies:
771 myeit() Mapping from csh alias "parameter referencing" into zsh function
772 (assuming tt(SH_WORD_SPLIT) and tt(KSH_ARRAYS) are NOT set in zsh):
779 \!:2 $2 (or $argv[2], etc.)
780 \!$ $*[$#] (or $argv[$#], or $*[-1])
782 \!:1- $*[1,$#-1] (or $*[1,-2])
785 \!*:x $=* ($*:x doesn't work (yet))
788 myeit() Remember that it is NOT a syntax error in a zsh function to
789 refer to a position (tt($1), tt($2), etc.) greater than the number of
790 parameters. (E.g., in a csh alias, a reference to tt(\!:5) will
791 cause an error if 4 or fewer arguments are given; in a zsh
792 function, tt($5) is the empty string if there are 4 or fewer
795 myeit() To begin a zsh alias with a - (dash, hyphen) character, use
799 =============== ==================
800 alias - "fg %-" alias -- -="fg %-"
803 myeit() Stay away from mytt(alias -g) in zsh until you REALLY know what
807 There is one other serious problem with aliases: consider
810 l() { /bin/ls -la "$@" | more }
812 mytt(l) in the function definition is in command position and is expanded
813 as an alias, defining mytt(/bin/ls) and mytt(-F) as functions which call
814 mytt(/bin/ls), which gets a bit recursive. This can be avoided if you use
815 mytt(function) to define a function, which doesn't expand aliases. It is
816 possible to argue for extra warnings somewhere in this mess.
818 Bart Schaefer's rule is: Define first those aliases you expect to
819 use in the body of a function, but define the function first if the
820 alias has the same name as the function.
823 sect(Similarities with tcsh)
825 (The sections on csh apply too, of course.) Certain features have
826 been borrowed from tcsh, including tt($watch), tt(run-help), tt($savehist),
827 periodic commands etc., extended prompts, tt(sched) and tt(which) built-ins.
828 Programmable completion was inspired by, but is entirely different to,
829 tcsh's mytt(complete). (There is a perl script called tt(lete2ctl) in the
830 Misc directory of the source distribution to convert mytt(complete) to \
832 statements.) This list is not definitive: some features have gone in
835 If you're missing the editor function tt(run-fg-editor), try something
836 with mytt(bindkey -s) (which binds a string to a keystroke), e.g.
838 bindkey -s '^z' '\eqfg %$EDITOR:t\n'
840 which pushes the current line onto the stack and tries to bring a job
841 with the basename of your editor into the foreground. mytt(bindkey -s)
842 allows limitless possibilities along these lines. You can execute
843 any command in the middle of editing a line in the same way,
844 corresponding to tcsh's mytt(-c) option:
846 bindkey -s '^p' '\eqpwd\n'
848 In both these examples, the mytt(\eq) saves the current input line to
849 be restored after the command runs; a better effect with multiline
850 buffers is achieved if you also have
852 bindkey '\eq' push-input
854 to save the entire buffer. In version 4 and recent versions of zsh 3.1,
855 you have the following more sophisticated option,
859 BUFFER="fg %$EDITOR:t"
864 and can now bind tt(run-fg-editor) just like any other editor function.
867 sect(Similarities with bash)
869 The Bourne-Again Shell, bash, is another enhanced Bourne-like shell;
870 the most obvious difference from zsh is that it does not attempt to
871 emulate the Korn shell. Since both shells are under active
872 development it is probably not sensible to be too specific here.
873 Broadly, bash has paid more attention to standards compliancy
874 (i.e. POSIX) for longer, and has so far avoided the more abstruse
875 interactive features (programmable completion, etc.) that zsh has.
877 In recent years there has been a certain amount of crossover in the
878 extensions, however. Zsh (as of 3.1.6) has bash's `tt(${var/old/new})'
879 feature for replacing the text tt(old) with the text tt(new) in the
880 parameter tt($var). Note one difference here: while both shells
881 implement the syntax `tt(${var/#old/new})' and `tt(${var/%old/new})' for
882 anchoring the match of tt(old) to the start or end of the parameter text,
883 respectively, in zsh you can't put the `tt(#)' or `tt(%)' inside a
884 parameter: in other words `tt({var/$old/new})' where tt(old) begins with
885 a `tt(#)' treats that as an ordinary character in zsh, unlike bash. To
886 do this sort of thing in zsh you can use (from 3.1.7) the new syntax
887 for anchors in any pattern, `tt((#s))' to match the start of a string,
888 and `tt((#e))' to match the end. These require the option
889 tt(EXTENDED_GLOB) to be set.
892 sect(Shouldn't zsh be more/less like ksh/(t)csh?)
894 People often ask why zsh has all these `unnecessary' csh-like features,
895 or alternatively why zsh doesn't understand more csh syntax. This is
896 far from a definitive answer and the debate will no doubt continue.
898 Paul's object in writing zsh was to produce a ksh-like shell which
899 would have features familiar to csh users. For a long time, csh was
900 the preferred interactive shell and there is a strong resistance to
901 changing to something unfamiliar, hence the additional syntax and
902 tt(CSH_JUNKIE) options. This argument still holds. On the other hand,
903 the arguments for having what is close to a plug-in replacement for ksh
904 are, if anything, even more powerful: the deficiencies of csh as a
905 programming language are well known (look in any Usenet FAQ archive, e.g.
906 url(http://www.cis.ohio-state.edu/hypertext/faq/usenet/unix-faq/\
907 shell/csh-whynot/faq.html)
908 (http://www.cis.ohio-state.edu/hypertext/faq/usenet/unix-faq/shell/csh-whynot/faq.html)
909 if you are in any doubt) and zsh is able to run many standard
910 scripts such as /etc/rc.
912 Of course, this makes zsh rather large and feature-ridden so that it
913 seems to appeal mainly to hackers. The only answer, perhaps not
914 entirely satisfactory, is that you have to ignore the bits you don't
915 want. The introduction of loadable in modules in version 3.1 should
919 sect(What is zsh's support for Unicode/UTF-8?)
921 `Unicode', or UCS for Universal Character Set, is the modern way
922 of specifying character sets. It replaces a large number of ad hoc
923 ways of supporting character sets beyond ASCII. `UTF-8' is an
924 encoding of Unicode that is particularly natural on Unix-like systems.
926 Q: Does zsh support UTF-8?
928 A: zsh's built-in printf command supports "\u" and "\U" escapes
929 to output arbitrary Unicode characters. ZLE (the Zsh Line Editor) has
930 no concept of character encodings, and is confused by multi-octet
933 Q: Why doesn't zsh have proper UTF-8 support?
935 A: The code has not been written yet.
937 Q: What makes UTF-8 support difficult to implement?
939 A: In order to handle arbitrary encodings the correct way, significant
940 and intrusive changes must be made to the shell.
942 Q: Why can't zsh just use readline?
944 A: ZLE is not encapsulated from the rest of the shell. Isolating it
945 such that it could be replaced by readline would be a significant
946 effort. Furthermore, using readline would effect a significant loss of
949 Q: What changes are planned?
951 A: Introduction of Unicode support will be gradual, so if you are
952 interested in being involved you should join the zsh-workers mailing
953 list. As a first step ZLE will be rewritten to use wide characters
954 internally. Character based widgets can then operate on a single wide
955 character instead of a single byte, and the proper display width can be
956 calculated with wcswidth().
959 chapter(How to get various things to work)
961 sect(Why does mytt($var) where mytt(var="foo bar") not do what I expect?)
964 In most Bourne-shell derivatives, multiple-word variables such as
968 are split into words when passed to a command or used in a mytt(for foo in
969 $var) loop. By default, zsh does not have that behaviour: the
970 variable remains intact. (This is not a bug! See below.) The option
971 tt(SH_WORD_SPLIT) exists to provide compatibility.
973 For example, defining the function args to show the number of its
978 and with our definition of `var',
982 produces the output `1'. After
986 the same function produces the output `2', as with sh and ksh.
988 Unless you need strict sh/ksh compatibility, you should ask yourself
989 whether you really want this behaviour, as it can produce unexpected
990 effects for variables with entirely innocuous embedded spaces. This
991 can cause horrendous quoting problems when invoking scripts from
992 other shells. The natural way to produce word-splitting behaviour
993 in zsh is via arrays. For example,
995 set -A array one two three twenty
999 array=(one two three twenty)
1001 if you prefer), followed by
1005 produces the output `4', regardless of the setting of tt(SH_WORD_SPLIT).
1006 Arrays are also much more versatile than single strings. Probably
1007 if this mechanism had always been available there would never have
1008 been automatic word splitting in scalars, which is a sort of
1009 uncontrollable poor man's array.
1011 Note that this happens regardless of the value of the internal field
1012 separator, tt($IFS); in other words, with mytt(IFS=:; foo=a:b; args $foo)
1013 you get the answer 1.
1015 Other ways of causing word splitting include a judicious use of
1018 sentence="Longtemps, je me suis couch\\'e de bonne heure."
1019 eval "words=($sentence)"
1021 after which $words is an array with the words of $sentence (note
1022 characters special to the shell, such as the mytt(') in this example,
1023 must already be quoted), or, less standard but more reliable,
1024 turning on tt(SH_WORD_SPLIT) for one variable only:
1028 always returns 8 with the above definition of mytt(args). (In older
1029 versions of zsh, tt(${=foo}) toggled tt(SH_WORD_SPLIT); now it forces it on.)
1031 Note also the tt("$@") method of word splitting is always available in zsh
1032 functions and scripts (though strictly this does array splitting, not
1033 word splitting). This is more portable than the tt($*), since it
1034 will work regardless of the tt(SH_WORD_SPLIT) setting; the other
1035 difference is that tt($*) removes empty arguments from the array.
1036 You can fix the first half of that objection by using tt(${==*}),
1037 which turns off tt(SH_WORD_SPLIT) for the duration of the expansion.
1039 tt(SH_WORD_SPLIT) is set when zsh is invoked with the names `ksh' or `sh',
1040 or (entirely equivalent) when mytt(emulate ksh) or mytt(emulate sh) is in
1043 There is one other effect of word splitting which differs between ksh
1044 and zsh. In ksh, the builtin commands that declare parameters such
1045 as tt(typeset) and tt(export) force word-splitting not to take place
1046 after on an assignment argument:
1048 typeset param=`echo foo bar`
1050 in ksh will create a parameter with value mytt(foo bar), but in zsh will
1051 create a parameter tt(param) with value tt(foo) and a parameter tt(bar)
1052 whose value is empty. Contrast this with a normal assignment (no
1053 tt(typeset) or other command in front), which never causes a word split
1054 unless you have tt(GLOB_ASSIGN) set. From zsh version 4.0.2 the option
1055 tt(KSH_TYPESET), set automatically in compatibility mode, fixes this
1056 problem. Note that in bash this behaviour occurs with all arguments that
1057 look like assignments, whatever the command name; to get this behaviour
1058 in zsh you have to set the option tt(MAGIC_EQUAL_SUBST).
1060 sect(In which startup file do I put...?)
1062 When zsh starts up, there are four files you can change which it will
1063 run under various circumstances: tt(.zshenv), tt(.zprofile), tt(.zshrc)
1064 and tt(.zlogin). They are usually in your home directory, but the
1065 variable tt($ZDOTDIR) may be set to alter that. Here are a few simple
1066 hints about how to use them. There are also files which the system
1067 administrator can set for all shells; you can avoid running all except
1068 tt(/etc/zshenv) by starting zsh with the tt(-f) option --- for this
1069 reason it is important for administrators to make sure tt(/etc/zshenv)
1070 is as brief as possible.
1072 The order in which the four files are searched (none of them myem(need)
1073 to exist) is the one just given. However, tt(.zprofile) and tt(.zlogin)
1074 are only run when the shell is a login shell --- when you first login,
1075 of course, and whenever you start zsh with the tt(-l) option. All
1076 login shells are interactive. The order is the only difference
1077 between those; you should decide whether you need things set before or
1078 after tt(.zshrc). These files are a good place to set environment
1079 variables (i.e. mytt(export) commands), since they are passed on to
1080 all shells without you having to set them again, and also to check
1081 that your terminal is set up properly (except that if you want to
1082 change settings for terminal emulator windows like tt(xterm) you will
1083 need to put those in tt(.zshrc), since usually you do not get a login
1086 The only file you can alter which is started with every zsh (unless
1087 you use the tt(-f) option) is tt(.zshenv), so this is a good place to \
1089 things you want even if the shell is non-interactive: options for
1090 changing the syntax, like tt(EXTENDED_GLOB), any changes to set with
1091 mytt(limit), any more variables you want to make sure are set as for
1092 example tt($fpath) to find functions. You almost certainly do not
1093 want tt(.zshenv) to produce any output. Some people prefer not to
1094 use tt(.zshenv) for setting options, as this affects scripts; but
1095 making zsh scripts portable usually requires special handling anyway.
1097 Finally, tt(.zshrc) is run for every interactive shell; that includes
1098 login shells, but also any other time you start up a shell, such as
1099 simply by typing mytt(zsh) or opening a new terminal emulator window.
1100 This file is the place to change the editing behaviour via options or
1101 mytt(bindkey), control how your history is saved, set aliases unless
1102 you want to use them in scripts too, and for any other clutter which
1103 can't be exported but you only use when interacting directly with the
1104 shell. You probably don't want tt(.zshrc) to produce output, either,
1105 since there are occasions when this can be a problem, such as when
1106 using mytt(rsh) from another host. See link(3.21)(321) for what to \
1108 to save your history.
1111 sect(What is the difference between `export' and the tt(ALL_EXPORT) option?)
1113 Normally, you would put a variable into the environment by using
1114 mytt(export var). The command mytt(setopt allexport) causes all
1115 variables which are subsequently set (N.B. not all the ones which
1116 already exist) to be put into the environment.
1118 This may seem a useful shorthand, but in practice it can have
1119 unhelpful side effects:
1121 myeit() Since every variable is in the environment as well as remembered
1122 by the shell, the memory for it needs to be allocated twice.
1123 This is bigger as well as slower.
1124 myeit() It really is mybf(every) variable which is exported, even loop
1125 variables in mytt(for) loops. This is probably a waste.
1126 myeit() An arbitrary variable created by the user might have a special
1127 meaning to a command. Since all shell variables are visible to
1128 commands, there is no protection against this.
1130 For these reasons it is usually best to avoid tt(ALL_EXPORT) unless you
1131 have a specific use for it. One safe use is to set it before
1132 creating a list of variables in an initialisation file, then unset
1133 it immediately afterwards. Only those variables will be automatically
1137 sect(How do I turn off spelling correction/globbing for a single command?)
1139 In the first case, you presumably have mytt(setopt correctall) in an
1140 initialisation file, so that zsh checks the spelling of each word in
1141 the command line. You probably do not want this behaviour for
1142 commands which do not operate on existing files.
1144 The answer is to alias the offending command to itself with
1145 mytt(nocorrect) stuck on the front, e.g.
1147 alias mkdir='nocorrect mkdir'
1150 To turn off globbing, the rationale is identical:
1152 alias mkdir='noglob mkdir'
1154 You can have both tt(nocorrect) and tt(noglob), if you like, but the
1155 tt(nocorrect) must come first, since it is needed by the line editor,
1156 while tt(noglob) is only handled when the command is examined.
1158 Note also that a shell function won't work: the no... directives must
1159 be expanded before the rest of the command line is parsed.
1162 sect(How do I get the Meta key to work on my xterm?)
1165 The Meta key isn't present on a lot of keyboards, but on some
1166 the Alt key has the same effect. If a character is typed on the
1167 keyboard while the Meta key is held down, the characters is sent
1168 as terminal input with its eighth bit set. For example, ASCII
1169 mytt(A), hex 65, becomes hex E5. This is sometimes used to provide
1170 extra editing commands.
1172 As stated in the manual, zsh needs to be told about the Meta key by
1173 using mytt(bindkey -me) or mytt(bindkey -mv) in your .zshrc or on the
1174 command line. You probably also need to tell the terminal driver to
1175 allow the `Meta' bit of the character through; mytt(stty pass8) is the
1176 usual incantation. Sample .zshrc entry:
1178 [[ $TERM = "xterm" ]] && stty pass8 && bindkey -me
1180 or, on SYSVR4-ish systems without pass8,
1182 [[ $TERM = "xterm" ]] && stty -parenb -istrip cs8 && bindkey -me
1184 (disable parity detection, don't strip high bit, use 8-bit characters).
1185 Make sure this comes myem(before) any bindkey entries in your .zshrc which
1186 redefine keys normally defined in the emacs/vi keymap. You may also
1187 need to set the tt(eightBitOutput) resource in your tt(~/.Xdefaults)
1188 file, although this is on by default and it's unlikely anybody will
1189 have tinkered with it.
1191 You don't need the mytt(bindkey) to be able to define your own sequences
1192 with the Meta key, though you still need the mytt(stty).
1194 If you are using multibyte input directly from the keyboard you
1195 probably don't want to use this feature since the eighth bit in
1196 each byte is used to indicate a part of a multibyte character. See
1197 link(chapter 5)(c5).
1200 sect(How do I automatically display the directory in my xterm title bar?)
1202 You should use the special function mytt(chpwd), which is called when
1203 the directory changes. The following checks that standard output is
1204 a terminal, then puts the directory in the title bar if the terminal
1205 is an tt(xterm) or some close relative, or a tt(sun-cmd).
1209 [[ -t 1 ]] || return
1211 sun-cmd+CHAR(41) print -Pn "\e]l%~\e\\"
1213 *xterm*|rxvt|(dt|k|E)term+CHAR(41) print -Pn "\e]2;%~\a"
1219 Change mytt(%~) if you want the message to be different. (The mytt(-P)
1220 option interprets such sequences just like in prompts, in this case
1221 producing the current directory; you can of course use mytt($PWD) here,
1222 but that won't use the mytt(~) notation which I find clearer.) Note that
1223 when the tt(xterm) starts up you will probably want to call tt(chpwd)
1224 directly: just put mytt(chpwd) in tt(.zshrc) after it is defined or \
1228 sect(How do I make the completion list use eight bit characters?)
1230 If you are sure your terminal handles this, the easiest way from versions
1231 3.0.6 and 3.1 of the shell is to set the option tt(PRINT_EIGHT_BIT). In
1232 principle, this will work automatically if your computer uses the
1233 `locale' system and your locale variables are set properly, as zsh
1234 understands this. However, it is quite complicated, so if it isn't
1235 already set up, trying the option is a lot easier. For earlier versions
1236 of zsh 3, you are stuck with trying to understand locales, see the
1237 tt(setlocale(3)) and tt(zshparam(1)) manual pages: the simplest
1238 possibility may be to set tt(LC_ALL=en_US). For older versions of the
1239 shell, there is no easy way out.
1242 sect(Why do the cursor (arrow) keys not work?)
1244 The cursor keys send different codes depending on the terminal; zsh
1245 only binds the most well known versions. If you see these problems,
1246 try putting the following in your tt(.zshrc):
1249 bindkey "$(echotc kl)" backward-char
1250 bindkey "$(echotc kr)" forward-char
1251 bindkey "$(echotc ku)" up-line-or-history
1252 bindkey "$(echotc kd)" down-line-or-history
1255 If you use vi mode, use mytt(vi-backward-char) and mytt(vi-forward-char)
1256 where appropriate. As of version 4.0.1, zsh attempts to look up these
1257 codes and to set the key bindings for you (both emacs and vi), but in
1258 some circumstances this may not work.
1260 Note, however, that up to version 3.0 binding arbitrary multiple key
1261 sequences can cause problems, so check that this works with your set
1262 up first. Also, from version 3.1.3, more sequences are supported by
1263 default, namely those in the form mytt(<ESC>O) followed by tt(A),
1264 tt(B), tt(C) or tt(D), as well as the corresponding set beginning
1265 mytt(<ESC>[), so this may be redundant.
1267 A particular problem which sometimes occurs is that there are two
1268 different modes for arrow keys, normal mode and keypad mode, which
1269 send different sequences. Although this is largely a historical
1270 artifact, it sometimes happens that your terminal can be switched from
1271 one mode to the other, for example by a rogue programme that sends the
1272 sequence to switch one way, but not the sequence to switch back. Thus
1273 you are stuck with the effects. Luckily in this case the arrow key
1274 sequences are likely to be standard, and you can simply bind both sets.
1275 The following code does this.
1277 bindkey '\e[A' up-line-or-history
1278 bindkey '\e[B' down-line-or-history
1279 bindkey '\e[C' forward-char
1280 bindkey '\e[D' backward-char
1281 bindkey '\eOA' up-line-or-history
1282 bindkey '\eOB' down-line-or-history
1283 bindkey '\eOC' forward-char
1284 bindkey '\eOD' backward-char
1286 For most even vaguely VT100-compatible terminals, the above eight
1287 instructions are a fairly safe bet for your tt(.zshrc). Of course
1288 you can substitute variant functions for the second argument here too.
1291 sect(Why does my terminal act funny in some way?)
1293 If you are using an OpenWindows cmdtool as your terminal, any
1294 escape sequences (such as those produced by cursor keys) will be
1295 swallowed up and never reach zsh. Either use shelltool or avoid
1296 commands with escape sequences. You can also disable scrolling from
1297 the cmdtool pane menu (which effectively turns it into a shelltool).
1298 If you still want scrolling, try using an xterm with the scrollbar
1301 If that's not the problem, and you are using stty to change some tty
1302 settings, make sure you haven't asked zsh to freeze the tty settings:
1307 before any stty commands you use.
1309 On the other hand, if you aren't using stty and have problems you may
1310 need the opposite: mytt(ttyctl -f) freezes the terminal to protect it
1311 from hiccups introduced by other programmes (kermit has been known to
1314 A problem I have experienced myself (on an AIX 3.2 workstation with
1315 xterm) is that termcap deinitialization sequences sent by `less'
1316 were causing automargins to be turned off --- not actually a shell
1317 problem, but you might have thought it was. The fix is to put `tt(X)'
1318 into the environment variable tt(LESS) to stop the sequences being sent.
1319 Other programs (though not zsh) may also send that sequence.
1321 If myem(that)'s not the problem, and you are having difficulties with
1322 external commands (not part of zsh), and you think some terminal
1323 setting is wrong (e.g. tt(^V) is getting interpreted as `literal next
1324 character' when you don't want it to be), try
1327 STTY='lnext "^-"' commandname
1329 (in this example). Note that zsh doesn't reset the terminal completely
1330 afterwards: just the modes it uses itself and a number of special
1331 processing characters (see the tt(stty(1)) manual page).
1334 sect(Why does zsh not work in an Emacs shell mode any more?)
1336 (This information comes from Bart Schaefer and other zsh-workers.)
1338 Emacs 19.29 or thereabouts stopped using a terminal type of "emacs"
1339 in shell buffers, and instead sets it to "dumb". Zsh only kicks in
1340 its special I'm-inside-emacs initialization when the terminal type
1343 Probably the most reliable way of dealing with this is to look for
1344 the environment variable mytt($EMACS), which is set to mytt(t) in
1345 Emacs' shell mode. Putting
1347 [[ $EMACS = t ]] && unsetopt zle
1349 in your .zshrc should be sufficient.
1351 Another method is to put
1356 into a file ~/bin/eshell, then mytt(chmod +x ~/bin/eshell), and
1357 tell emacs to use that as the shell by adding
1359 (setenv "ESHELL" (expand-file-name "~/bin/eshell"))
1364 sect(Why do my autoloaded functions not autoload [the first time]?)
1366 The problem is that there are two possible ways of autoloading a
1367 function (see the AUTOLOADING FUNCTIONS section of the zsh manual
1368 page zshmisc for more detailed information):
1370 myeit() The file contains just the body of the function, i.e.
1371 there should be no line at the beginning saying mytt(function foo {)
1372 or mytt(foo () {), and consequently no matching mytt(}) at the end.
1373 This is the traditional zsh method. The advantage is that the
1374 file is called exactly like a script, so can double as both.
1375 To define a function mytt(xhead () { print -n "\033]2;$*\a"; }),
1376 the file would just contain mytt(print -n "\033]2;$*\a").
1377 myeit() The file contains the entire definition, and maybe even
1378 other code: it is run when the function needs to be loaded, then
1379 the function itself is called up. This is the method in ksh.
1380 To define the same function mytt(xhead), the whole of the
1381 usual definition should be in the file.
1384 In old versions of zsh, before 3.0, only the first behaviour was
1385 allowed, so you had to make sure the file found for autoload just
1386 contained the function body. You could still define other functions
1387 in the file with the standard form for definitions, though they
1388 would be redefined each time you called the main function.
1390 In version 3.0.x, the second behaviour is activated if the file
1391 defines the autoloaded function. Unfortunately, this is
1392 incompatible with the old zsh behaviour which allowed you to
1393 redefine the function when you called it.
1395 From version 3.1, there is an option tt(KSH_AUTOLOAD) to allow full ksh
1396 compatiblity, i.e. the function myem(must) be in the second form
1397 above. If that is not set, zsh tries to guess which form you are
1398 using: if the file contains only a complete definition of the
1399 function in the second form, and nothing else apart from comments
1400 and whitespace, it will use the function defined in the file;
1401 otherwise, it will assume the old behaviour. The option is set
1402 if mytt(emulate ksh) is in effect, of course.
1404 (A neat trick to autoload all functions in a given directory is to
1405 include a line like mytt(autoload ~/fns/*(:t)) in .zshrc; the bit in
1406 parentheses removes the directory part of the filenames, leaving
1407 just the function names.)
1410 sect(How does base arithmetic work?)
1412 The ksh syntax is now understood, i.e.
1424 The original syntax was
1428 --- this was based on a misunderstanding of the ksh manual page. It
1429 still works but its use is deprecated. Then
1433 gives the answer `255'. It is possible to declare variables explicitly
1438 which has a different effect: namely the base used in the first
1439 assignment (hexadecimal in the example) is subsequently used whenever
1440 `foo' is displayed (although the internal representation is unchanged).
1441 To ensure foo is always displayed in decimal, declare it as
1445 which requests base 10 for output. You can change the output base of an
1446 existing variable in this fashion. Using the mytt($(( ... ))) method will
1447 always display in decimal, except that in 3.1.9 there is a new feature
1448 for selecting a base for displaying here:
1450 print $(( [#16] 255 ))
1454 sect(How do I get a newline in my prompt?)
1457 You can place a literal newline in quotes, i.e.
1462 If you have the bad taste to set the option cshjunkiequotes, which
1463 inhibits such behaviour, you will have to bracket this with
1464 mytt(unsetopt cshjunkiequotes) and mytt(setopt cshjunkiequotes), or put it
1465 in your tt(.zshrc) before the option is set.
1467 In recent versions of zsh (not 3.0), there is a form of quoting which
1468 interprets print sequences like `tt(\n)' but otherwise acts like single
1469 quotes: surround the string with tt($'...'). Hence:
1471 PROMPT=$'Hi Joe,\nwhat now?%# '
1473 is a neat way of doing what you want. Note that it is the quotes, not
1474 the prompt expansion, which turns the `tt(\n)' into a newline.
1477 sect(Why does mytt(bindkey ^a command-name) or mytt(stty intr ^-) do something funny?)
1479 You probably have the extendedglob option set in which case tt(^) and tt(#)
1480 are metacharacters. tt(^a) matches any file except one called tt(a), so the
1481 line is interpreted as bindkey followed by a list of files. Quote the
1482 tt(^) with a backslash or put quotation marks around tt(^a).
1485 sect(Why can't I bind tt(\C-s) and tt(\C-q) any more?)
1487 The control-s and control-q keys now do flow control by default,
1488 unless you have turned this off with mytt(stty -ixon) or redefined the
1489 keys which control it with mytt(stty start) or mytt(stty stop). (This is
1490 done by the system, not zsh; the shell simply respects these
1491 settings.) In other words, tt(\C-s) stops all output to the terminal,
1492 while tt(\C-q) resumes it.
1494 There is an option tt(NO_FLOW_CONTROL) to stop zsh from allowing flow
1495 control and hence restoring the use of the keys: put mytt(setopt
1496 noflowcontrol) in your tt(.zshrc) file.
1499 sect(How do I execute command mytt(foo) within function mytt(foo)?)
1501 The command mytt(command foo) does just that. You don't need this with
1502 aliases, but you do with functions. Note that error messages like
1504 zsh: job table full or recursion limit exceeded
1506 are a good sign that you tried calling `foo' in function `foo' without
1507 using `command'. If mytt(foo) is a builtin rather than an external
1508 command, use mytt(builtin foo) instead.
1511 sect(Why do history substitutions with single bangs do something funny?)
1513 If you have a command like "tt(echo !-2:$ !$)", the first history
1514 substitution then sets a default to which later history substitutions
1515 with single unqualified bangs refer, so that !$ becomes equivalent to
1516 tt(!-2:$). The option tt(CSH_JUNKIE_HISTORY) makes all single bangs refer
1517 to the last command.
1520 sect(Why does zsh kill off all my background jobs when I logout?)
1522 Simple answer: you haven't asked it not to. Zsh (unlike [t]csh) gives
1523 you the option of having background jobs killed or not: the mytt(nohup)
1524 option exists if you don't want them killed. Note that you can always
1525 run programs with mytt(nohup) in front of the pipeline whether or not the
1526 option is set, which will prevent that job from being killed on
1527 logout. (mytt(nohup) is actually an external command.)
1529 The mytt(disown) builtin is very useful in this respect: if zsh informs
1530 you that you have background jobs when you try to logout, you can
1531 mytt(disown) all the ones you don't want killed when you exit. This is
1532 also a good way of making jobs you don't need the shell to know about
1533 (such as commands which create new windows) invisible to the shell.
1534 Likewise, you can start a background job with mytt(&!) instead of just
1535 mytt(&) at the end, which will automatically disown the job.
1538 sect(How do I list all my history entries?)
1540 Tell zsh to start from entry 1: mytt(history 1). Those entries at the
1541 start which are no longer in memory will be silently omitted.
1544 sect(How does the alternative loop syntax, e.g. mytt(while {...} {...}) \
1547 Zsh provides an alternative to the traditional sh-like forms with mytt(do),
1549 while TEST; do COMMANDS; done
1551 allowing you to have the COMMANDS delimited with some other command
1552 structure, often mytt({...}). The rules are quite complicated and
1553 in most scripts it is probably safer --- and certainly more
1554 compatible --- to stick with the sh-like rules. If you are
1555 wondering, the following is a rough guide.
1557 To make it work you must make sure the TEST itself is clearly
1558 delimited. For example, this works:
1560 while (( i++ < 10 )) { echo i is $i; }
1562 but this does myem(not):
1564 while let "i++ < 10"; { echo i is $i; } # Wrong!
1566 The reason is that after mytt(while), any sort of command list is valid.
1567 This includes the whole list mytt(let "i++ < 10"; { echo i $i; });
1568 the parser simply doesn't know when to stop. Furthermore, it is
1569 wrong to miss out the semicolon, as this makes the mytt({...}) part
1570 of the argument to mytt(let). A newline behaves the same as a
1571 semicolon, so you can't put the brace on the next line as in C.
1573 So when using this syntax, the test following the mytt(while) must
1574 be wrapped up: any of mytt(((...))), mytt([[...]]), mytt({...}) or
1575 mytt((...)) will have this effect. (They have their usual syntactic
1576 meanings too, of course; they are not interchangeable.) Note that
1577 here too it is wrong to put in the semicolon, as then the case
1578 becomes identical to the preceding one:
1580 while (( i++ < 10 )); { echo i is $i; } # Wrong!
1583 The same is true of the mytt(if) and mytt(until) constructs:
1585 if { true } { echo yes } else { echo no }
1587 but with mytt(for), which only needs a list of words, you can get
1590 for foo in a b; { echo foo is $a; bar=$foo; }
1592 since the parser knows it only needs everything up to the first
1593 semicolon. For the same reason, there is no problem with the mytt(repeat),
1594 mytt(case) or mytt(select) constructs; in fact, mytt(repeat) doesn't even
1595 need the semicolon since it knows the repeat count is just one word.
1597 This is independent of the behaviour of the SHORTLOOPS option (see
1598 manual), which you are in any case encouraged even more strongly not
1599 to use in programs as it can be very confusing.
1602 sect(Why is my history not being saved?)
1605 In zsh, you need to set three variables to make sure your history is
1606 written out when the shell exits. For example,
1609 HISTFILE=~/.zsh_history
1612 tt($HISTSIZE) tells the shell how many lines to keep internally,
1613 tt($HISTFILE) tells it where to write the history, and tt($SAVEHIST),
1614 the easiest one to forget, tells it how many to write out. The
1615 simplest possibility is to set it to the same as tt($HISTSIZE) as
1616 above. There are also various options affecting history; see the
1620 sect(How do I get a variable's value to be evaluated as another variable?)
1622 The problem is that you have a variable tt($E) containing the string
1623 mytt(EDITOR), and a variable tt($EDITOR) containing the string mytt(emacs),
1624 or something such. How do you get from tt($E) to emacs in one easy
1627 There is no standard single-stage way of doing this. However, there
1628 is a zsh idiom (available in all versions of zsh since 3.0) for this:
1632 Ignore the mytt((e)) for now. The mytt(:+) means: if the variable
1633 tt($E) is set, substitute the following, i.e. mytt(\$$E). This is
1634 expanded to mytt($EDITOR) by the normal rules. Finally, the mytt((e)) \
1636 `evaluate the expression you just made'. This gives mytt(emacs).
1638 For a standard shell way of doing this, you are stuck with mytt(eval):
1642 produces the same result.
1644 Versions since 3.1.6 allow you to do this directly with a new flag;
1647 As a slight aside, sometimes people note that the syntax mytt(${${E}})
1648 is valid and expect it to have this effect. It probably ought to, but
1649 in the early days of zsh it was found convenient to have this way of
1650 producing different substitutions on the same parameter; for example,
1651 mytt(${${file##**/}%.*}) removes everything up to the last slash in
1652 mytt($file), then everything from the last dot on, inclusive (try
1653 it, this works). So in mytt(${${E}}), the internal mytt(${...})
1654 actually does nothing.
1657 sect(How do I prevent the prompt overwriting output when there is no newline?)
1659 The problem is normally limited to zsh versions prior to 4.3.0 due to the
1660 advent of the PROMPT_SP option (which is enabled by default, and eliminates
1661 this problem for most terminals). An example of the overwriting is:
1666 This shows a case where the word tt(foo) was output without a newline, and
1667 then overwritten by the prompt line tt(%). The reason this happens is that
1668 the option tt(PROMPT_CR) is enabled by default, and it outputs a carriage
1669 return before the prompt in order to ensure that the line editor knows what
1670 column it is in (this is needed to position the right-side prompt correctly
1671 (mytt($RPROMPT), mytt($RPS1)) and to avoid screen corruption when performing
1672 line editing). If you add tt(unsetopt promptcr) to your tt(.zshrc), you
1673 will see any partial output, but your screen may look weird until you press
1674 return or refresh the screen.
1676 A better solution than disabling PROMPT_CR (for most terminals) is adding
1677 a simpler version of the PROMPT_SP functionality to an older zsh using a
1678 custom precmd function, like this one:
1680 # Skip defining precmd if the PROMPT_SP option is available.
1681 if ! eval '[[ -o promptsp ]] 2>/dev/null'; then
1683 # Output an inverse char and a bunch spaces. We include
1684 # a CR at the end so that any user-input that gets echoed
1685 # between this output and the prompt doesn't cause a wrap.
1686 print -nP "%B%S%#%s%b${(l:$((COLUMNS-1)):::):-}\r"
1690 That precmd function will only bump the screen down to a new line if there
1691 was output on the prompt line, otherwise the extra chars get removed by
1692 the PROMPT_CR action. Although this typically looks fine, it may result
1693 in the spaces preceding the prompt being included when you select a line
1694 of preserved text with the mouse.
1696 One final alternative is to put a newline in your prompt -- see question
1697 link(3.13)(313) for that.
1699 sect(What's wrong with cut and paste on my xterm?)
1701 On the majority of modern UNIX systems, cutting text from one window and
1702 pasting it into another should work fine. On a few, however, there are
1703 problems due to issues about how the terminal is handled: most programs
1704 expect the terminal to be in `canonical input mode', which means that the
1705 program is passed a whole line of input at a time, while for editing
1706 the shell needs a single character at a time and must be in
1707 `non-canonical input mode'. On the systems in question, input can be
1708 lost or re-ordered when the mode changes. There are actually two
1709 slightly different problems:
1711 myeit() When you paste something in while a programme is running, so that
1712 the shell only retrieves it later. Traditionally, there was a test
1713 which was used only on systems where the problem was known to exist,
1714 so it is possible some other systems were not handled (for example,
1715 certain versions of IRIX, it appears); also, continuation lines were
1716 not handled properly. A more reliable approach appears from versions
1718 myeit() When the shell is waiting for input, and you paste in a chunk of
1719 text consisting of more than one complete set of commands.
1720 Unfortunately, this is a much harder problem: the line editor is
1721 already active, and needs to be turned off when the first command is
1722 executed. The shell doesn't even know if the remaining text is input
1723 to a command or for the shell, so there's simply nothing it can do.
1724 However, if you have problems you can trick it: type `tt({)' on a line
1725 by itself, then paste the input, then type `tt(})' on a line by
1726 itself. The shell will not execute anything until the final brace is
1727 read; all input is read as continuation lines (this may require the
1728 fixes referred to above in order to be reliable).
1731 sect(How do I get coloured prompts on my colour xterm?)
1733 (Or `color xterm', if you're reading this in black and white.) You need
1734 to find the sequences which generate the various colours from the manual
1735 for your terminal emulator; these are ANSI standard on those I know about
1736 which support colour. With a recent (post 3.1.6) distribution of zsh,
1737 there is a theme system to handle this for you; even if you don't see that,
1738 the installed function `mytt(colors)' (meaning `colours', if you're not
1739 reading this in black and white) gives the escape sequences. You will end
1740 up with code looking like this (borrowed from Oliver Kiddle):
1742 PS1=$'%{\e[1;31m%}<the rest of your prompt here>%{\e[0m%}'
1744 The mytt($') form of quoting turns the `mytt(\e)' into a real escape
1745 character; this only works from about version 3.1.4, so if you're using
1746 3.0.x, you need to do something like
1748 PS1="$(print '%{\e[1;31m%}<the rest goes here>%{\e[0m%}')"
1750 The `mytt(%{...%})' is used in prompts for strings which will
1751 not appear as characters, so that the prompt code doesn't miscalculate the
1752 length of the prompt which would have a bad effect on editing. The
1753 resulting `mytt(<ESC>[1;31m)' makes the prompt red, and the
1754 `mytt(<ESC>[0m)' puts printing back to normal so that the rest of the line
1757 sect(Why is my output duplicated with `tt(foo 2>&1 >foo.out | bar)'?)
1759 This is a slightly unexpected effect of the option tt(MULTIOS), which is
1760 set by default. Let's look more closely:
1762 foo 2>&1 >foo.out | bar
1764 What you're probably expecting is that the command mytt(foo) sends its
1765 standard output to the pipe and so to the input of the command mytt(bar),
1766 while it sends its standard error to the file mytt(foo.out). What you
1767 actually see is that the output is going both to the pipe and into the
1768 file. To be more explicit, here's the same example with real commands:
1770 % { print output; print error >&2 } 2>&1 >foo.out | sed 's/error/erratic'
1776 and you can see `tt(output)' appears twice.
1778 It becomes clearer what's going on if we write:
1780 % print output >foo1.out >foo2.out
1786 You might recognise this as a standard feature of zsh, called `tt(multios)'
1787 and controlled by the option of the same name, whereby output is copied
1788 to both files when the redirector appears twice. What's going on in the
1789 first example is exactly the same, however the second redirector is
1790 disguised as a pipe. So if you want to turn this effect off, you need
1791 to unset the option mytt(MULTIOS).
1794 chapter(The mysteries of completion)
1797 sect(What is completion?)
1799 `Completion' is where you hit a particular command key (TAB is the
1800 standard one) and the shell tries to guess the word you are typing
1801 and finish it for you --- a godsend for long file names, in
1802 particular, but in zsh there are many, many more possibilities than
1805 There is also a related process, `expansion', where the shell sees
1806 you have typed something which would be turned by the shell into
1807 something else, such as a variable turning into its value ($PWD
1808 becomes /home/users/mydir) or a history reference (!! becomes
1809 everything on the last command line). In zsh, when you hit TAB it
1810 will look to see if there is an expansion to be done; if there is,
1811 it does that, otherwise it tries to perform completion. (You can
1812 see if the word would be expanded --- not completed --- by TAB by
1813 typing mytt(\C-x g), which lists expansions.) Expansion is generally
1814 fairly intuitive and not under user control; for the rest of the
1815 chapter I will discuss completion only.
1817 An elegant completion system appeared in version 4, replacing the old
1818 tt(compctl) command. This is based on functions called automatically for
1819 completion in particular contexts (for example, there is a function
1820 called tt(_cd) to handle completion for the tt(cd) command) and is
1821 installed automatically with the shell, so all you need to do, in
1822 principal, is to arrange for this to be loaded. Putting `tt(autoload -U
1823 compinit; compinit)' in your tt(.zshrc) should be enough if the system is
1827 sect(What sorts of things can be completed?)
1830 The simplest sort is filename completion, mentioned above. Unless
1831 you have made special arrangements, as described below, then after
1832 you type a command name, anything else you type is assumed by the
1833 completion system to be a filename. If you type part of a word and
1834 hit TAB, zsh will see if it matches the first part a filename and
1835 if it does it will automatically insert the rest.
1837 The other simple type is command completion, which applies
1838 (naturally) to the first word on the line. In this case, zsh
1839 assumes the word is some command to be executed lying in your $PATH
1840 (or something else you can execute, like a builtin command, a
1841 function or an alias) and tries to complete that.
1843 However, the new completion system is highly sensitive to context
1844 and comes with completions for many UNIX commands. These are
1845 automatically loaded when you run tt(compinit) as described above.
1846 So the real answer to the question `what can be completed?' is
1847 `anything where an automated guess is possible'. Just hit TAB
1848 and see if the shell manages to guess correctly.
1851 sect(How does zsh deal with ambiguous completions?)
1853 Often there will be more than one possible completion: two files
1854 start with the same characters, for example. Zsh has a lot of
1855 flexibility for what it does here via its options. The default is
1856 for it to beep and completion to stop until you type another
1857 character. You can type tt(\C-D) to see all the possible completions.
1858 (That's assuming you're at the end of the line, otherwise tt(\C-D) will
1859 delete the next character and you have to use tt(ESC-\C-D).) This can be
1860 changed by the following options, among others:
1862 it() with tt(NO_BEEP) set, that annoying beep goes away
1863 it() with tt(NO_LIST_BEEP), beeping is only turned off for ambiguous
1865 it() with tt(AUTO_LIST) set, when the completion is ambiguous you get a
1866 list without having to type tt(\C-D)
1867 it() with tt(BASH_AUTO_LIST) set, the list only happens the second
1868 time you hit tab on an ambiguous completion
1869 it() with tt(LIST_AMBIGUOUS), this is modified so that nothing is listed if
1870 there is an unambiguous prefix or suffix to be inserted --- this
1871 can be combined with tt(BASH_AUTO_LIST), so that where both are
1872 applicable you need to hit tab three times for a listing.
1873 it() with tt(MENU_COMPLETE) set, one completion is always inserted
1874 completely, then when you hit TAB it changes to the next, and so
1875 on until you get back to where you started
1876 it() with tt(AUTO_MENU), you only get the menu behaviour when you hit TAB
1877 again on the ambiguous completion.
1878 it() Finally, although it affects all completion lists, including
1879 those explicitly requested, note also tt(ALWAYS_LAST_PROMPT), which
1880 causes the cursor to return to the line you were editing after
1881 printing the list, provided that is short enough.
1883 Combinations of these are possible; for example, tt(AUTO_LIST) and
1884 tt(AUTO_MENU) together give an intuitive combination. Note that
1885 from version 3.1 tt(LIST_AMBIGUOUS) is set by default; if you use
1886 autolist, you may well want to `unsetopt listambiguous'.
1889 sect(How do I complete in the middle of words / just what's before the cursor?)
1891 Sometimes you have a word on the command-line which is incomplete in the
1892 middle. Normally if you hit tab in zsh, it will simply go to the end of
1893 the word and try to complete there. However, there are two ways of
1896 First, there is the option COMPLETE_IN_WORD. This tries to fill in
1897 the word at the point of the cursor. For example, if the current
1898 directory contains mytt(foobar), then with the option set, you can
1899 complete mytt(fbar) to mytt(foobar) by moving the cursor to the
1900 mytt(b) and hitting tab.
1902 To complete just what's before the cursor, ignoring anything after, you
1903 need the function tt(expand-or-complete-prefix): it works mostly like the
1904 usual function bound to tab, but it ignores anything on the right of the
1905 cursor. If you always want this behaviour (some other shells do this),
1906 bind it to tab; otherwise put another binding, e.g. mytt(^X TAB) in
1909 bindkey "^X^I" expand-or-complete-prefix
1912 The completion system's handling of filenames allows you to complete
1913 multiple segments of a path in one go, so for example tt(/u/l/b)
1914 can expand to tt(/usr/local/bin) or anything else that matches. This
1915 saves you having to expand the middle part of the path separately.
1918 sect(How do I get started with programmable completion?)
1921 The main resource is the tt(zshcompsys) manual page. It's complicated,
1922 I'm afraid, far too much to go into here. See also the user guide
1923 referred to above, or copy one of the very many existing functions. For
1924 a professionally produced guide, see the book `From Bash to Z Shell:
1925 Conquering the Command Line' by Oliver Kiddle, Jerry Peek and Peter
1926 Stephenson (me), published by Apress, ISBN 1-59059-376-6. Chapter 10
1927 tells you how to configure the completion system and chapter 15 how
1928 to write your own completion functions.
1931 sect(Suppose I want to complete all files during a special completion?)
1933 If you're using the completion system the shell will decide what
1934 to complete when you hit TAB. That's usually the right thing for
1935 the context, but sometimes you just want to complete files, like
1936 TAB used to do in the old days. You can set up this up as follows:
1938 zle -C complete-file complete-word _generic
1939 zstyle ':completion:complete-file::::' completer _files
1940 bindkey '^xF' complete-file
1942 This turns the key tt(\C-x F) into a command tt(complete-file) which
1943 goes straight to the completion system's file completion command,
1944 ignoring the normal context. Change the binding how you like.
1946 Note the way the form of completion to use is specified by picking a
1947 `completer' called `tt(_files)'. You can define any completion
1948 to be bound to a keystroke by putting the appropriate completion
1949 function at that point. Then change all occurrences of
1950 `tt(complete-file)' to a name of your own.
1952 If you simply want to try filename completion as a default when other
1953 completions fail, add it to the `tt(completer)' style for normal
1954 completion, for example:
1956 zstyle ':completion:*' completer _complete _ignored _files
1958 This adds filename completion to the end of the default types of
1959 completion. Your actual completer style may include other actions,
1960 such as expansion or approximate completion.
1963 chapter(Multibyte input and output)
1966 sect(What is multibyte input?)
1968 For a long time computers had a simple idea of a character: each octet
1969 (8-bit byte) of text contained one character. This meant an application
1970 could only use 256 characters at once. The first 128 characters (0 to
1971 127) on Unix and similar systems usually corresponded to the ASCII
1972 character set, as they still do. So all other possibilities had to be
1973 crammed into the remaining 128. This was done by picking the appropriate
1974 character set for the use you were making. For example, ISO 8859
1975 specified a set of extensions to ASCII for various alphabets.
1977 This was fine for simple extensions and certain short enough relatives of
1978 the Latin alphabet (with no more than a few dozen alphabetic characters),
1979 but useless for complex alphabets. Also, having a different character
1980 set for each language is inconvenient: you have to start a new terminal
1981 to run the shell with each character set. So the character set had to be
1982 extended. To cut a long story short, the world has mostly standardised
1983 on a character set called Unicode, related to the international standard
1984 ISO 10646. The intention is that this will contain every single
1985 character used in all the languages of the world.
1987 This has far too many characters to fit into a single octet. What's
1988 more, UNIX utilities such as zsh are so used to dealing with ASCII that
1989 removing it would cause no end of trouble. So what happens is this: the
1990 128 ASCII characters are kept exactly the same (and they're the same as
1991 the first 128 characters of Unicode), but the remaining 128 characters
1992 are used to build up any other Unicode character by combining multiple
1993 octets together. The shell doesn't need to interpret these directly; it
1994 just needs to ask the system library how many octets form the next
1995 character, and if there's a valid character there at all. (It can also
1996 ask the system what width the character takes up on the screen, so that
1997 characters no longer need to be exacxtly one position wide.)
1999 The way this is done is called UTF-8. Multibyte encodings of other
2000 character sets exist (you might encounter them for Asian character sets);
2001 zsh will be able to use any such encoding as long as it contains ASCII as
2002 a single-octet subset and the system can provide information about other
2003 characters. However, in the case of Unicode, UTF-8 is the only one you
2004 are likely to enounter.
2006 (In case you're confused: Unicode is the character set, while UTF-8 is
2007 an encoding of it. You might hear about other encodings, such as UCS-2
2008 and UCS-4 which are basically the character's index in the character set
2009 as a two-octet or four-octet integer. You might see files encoded this
2010 way, for example on Windows, but the shell can't deal directly with text
2014 sect(How does zsh handle multibyte input and output?)
2016 Until version 4.3, zsh didn't handle multibyte input properly at all.
2017 Each octet in a multibyte character would look to the shell like a
2018 separate character. If your terminal handled the character set,
2019 characters might appear correct on screen, but trying to edit them would
2020 cause all sorts of odd effects. (It was possible to edit in zsh using
2021 single-byte extensions of ASCII such as the ISO 8859 family, however.)
2023 From version 4.3.4, multibyte input is handled in the line editor if zsh
2024 has been compiled with the appropriate definitions, and is automatically
2025 activated. This is indicated by the option tt(MULTIBYTE), which is
2026 set by default on shells that support multibyte mode. Hence you
2027 can test this with a standard option test: `tt([[ -o multibyte ]])'.
2029 The tt(MULTIBYTE) option affects the entire shell: parameter expansion,
2030 pattern matching, etc. count valid multibyte character strings as a
2031 single character. You can unset the option locally in a function to
2032 revert to single-byte operation.
2034 Note that if the shell is emulating a Bourne shell the tt(MULTIBYTE)
2035 option is unset by default. This allows various POSIX modes to
2036 work normally (POSIX does not deal with multibyte characters). If
2037 you use a "sh" or "ksh" emulation interactively you shouldprobably
2038 set the tt(MULTIBYTE) option.
2040 The other option that affects multibyte support is tt(COMBINING_CHARS),
2041 new in version 4.3.9. When this is set, any zero-length punctuation
2042 characters that follow an alphanumeric character (the base character) are
2043 assumed to be modifications (accents etc.) to the base character and to
2044 be displayed within the same screen area as the base character. As not
2045 all terminals handle this, even if they correctly display the base
2046 multibyte character, this option is not on by default. The KDE terminal
2047 emulator tt(konsole), tt(rxvt-unicode), and the Unicode version of
2048 xterm, tt(xterm -u8) or the front-end tt(uxterm), are known to handle
2049 combining characters.
2051 The tt(COMBINING_CHARS) option only affects output; combining characters
2052 may always be input, but when the option is off will be displayed
2053 specially. By default this is as a code point (the index of the
2054 character in the character set) between angle brackets, usually
2055 in inverse video. Highlighting of such special characters can
2056 be modified using the new array parameter tt(zle_highlight).
2059 sect(How do I ensure multibyte input and output work on my system?)
2061 Once you have a version of zsh with multibyte support, you need to
2062 ensure the environment is correct. We'll assume you're using UTF-8.
2063 Many modern systems may come set up correctly already. Try one of
2064 the editing widgets described in the next section to see.
2066 There are basically three components.
2069 it() The locale. This describes a whole series of features specific
2070 to countries or regions of which the character set is one. Usually
2071 it is controlled by the environment variable tt(LANG) (there are
2072 others but this is the one to start with). You need to find a
2073 locale whose name contains mytt(UTF-8). This will be a variant on
2074 your usual locale, which typically indicates the language and
2075 country; for example, mine is mytt(en_GB.UTF-8). Luckily, zsh can
2076 complete locale names, so if you have the new completion system
2077 loaded you can type mytt(export LANG=) and attempt to complete a
2078 suitable locale. It's the locale that tells the shell to expect the
2079 right form of multibyte input. (However, there's no guarantee that
2080 the shell is actually going to get this input: for example, if you
2081 edit file names that have been created using a different character
2082 set it won't work properly.)
2083 it() The terminal emulator. Those that are supplied with a recent
2084 desktop environment, such as gnome-terminal, are likely to have
2085 extensive support for localization and may work correctly as soon
2086 as they know the locale. You can enable UTF-8 support for
2087 tt(xterm) in its application defaults file. The following are
2088 the relevant resources; you don't actually need all of them, as
2089 described below. If you use a mytt(~/.Xdefaults) or
2090 mytt(~/.Xresources) file for setting resources, prefix all the lines
2096 *vt100Graphics: true
2098 This turns on support for wide characters (this is enabled by the
2099 tt(utf8) resource, too); enables conversions to UTF-8 from other
2100 locales (this is the key resource and actually overrides
2101 mytt(utf8)); turns on UTF-8 mode (this resource is mostly used to
2102 force use of UTF-8 characters if your locale system isn't up to it);
2103 and allows certain graphic characters to work even with UTF-8
2104 enabled. (Thanks to Phil Pennock for suggestions.)
2105 it() The font. If you selected this from a menu in your terminal
2106 emulator, there's a good chance it already selected the right
2107 character set to go with it. If you hand-picked an old fashioned
2108 X font with a lot of dashes, you need to make sure it ends with
2109 the right character encoding, mytt(iso10646-1) (and not, for
2110 example, mytt(iso8859-1)). Not all characters will be available
2111 in any font, and some fonts may have a more restricted range of
2112 Unicode characters than others.
2115 As mentioned in the previous section, mytt(bindkey -m) now outputs
2116 a warning message telling you that multibyte input from the terminal
2117 is likely not to work. (See link(3.5)(35) if you don't know what
2118 this feature does.) If your terminal doesn't have characters
2119 that need to be input as multibyte, however, you can still use
2120 the meta bindings and can ignore the warning message. Use
2121 mytt(bindkey -m 2>/dev/null) to suprress it.
2124 sect(How can I input characters that aren't on my keyboard?)
2126 Two functions are provided with zsh that help you input characters.
2127 As with all editing widgets implemented by functions, you need to
2128 mark the function for autoload, create the widget, and, if you are
2129 going to use it frequently, bind it to a key sequence. The
2130 following binds tt(insert-composed-char) to F5 on my keyboard:
2132 autoload -Uz insert-composed-char
2133 zle -N insert-composed-char
2134 bindkey '\e[15~' insert-composed-char
2137 The two widgets are described in the tt(zshcontrib(1)) manual
2138 page, but here is a brief summary:
2140 tt(insert-composed-char) is followed by two characters that
2141 are a mnemonic for a multibyte character. For example mytt(a:)
2142 is a with an Umlaut; mytt(cH) is the symbol for hearts on a playing
2143 card. Various accented characters, European and related alphabets,
2144 and punctuation and mathematical symbols are available. The
2145 mnemonics are mostly those given by RFC 1345, see
2146 url(http://www.faqs.org/rfcs/rfc1345.html)\
2147 (http://www.faqs.org/rfcs/rfc1345.html).
2149 tt(insert-unicode-char) is used to input a Unicode character by
2150 its hexadecimal number. This is the number given in the Unicode
2151 character charts, see for example \
2152 url(http://www.unicode.org/charts/)(http://www.unicode.org/charts/).
2153 You need to execute the function, then type the hexadecimal number
2154 (you can omit any leading zeroes), then execute the function again.
2156 Both functions can be used without multibyte mode, provided the locale is
2157 correct and the character selected exists in the current character set;
2158 however, using UTF-8 massively extends the number of valid characters
2159 that can be produced.
2161 See also url(http://www.cl.cam.ac.uk/~mgk25/unicode.html#input)(http://www.cl.cam.ac.uk/~mgk25/unicode.html#input)
2162 for general information on entering Unicode characters from a keyboard.
2165 chapter(The future of zsh)
2167 sect(What bugs are currently known and unfixed? (Plus recent \
2171 Bugs tend to be tracked on the zsh-workers mailing list; see the
2172 next section. Check the mailing list to see if a bug has been
2173 reported. (There is a bug tracker at the zsh development site
2174 at Sourceforge, but it's not in active use.)
2176 To see how recent versions of the shell have changed, look at
2177 the README file in the source distribution. This indicates the
2178 most important changes, and in particular draws attention to
2179 incompatibilities you might notice.
2182 sect(Where do I report bugs, get more info / who's working on zsh?)
2185 The shell is being maintained by various (entirely self-appointed)
2186 subscribers to the mailing list,
2188 zsh-workers@sunsite.dk
2190 so mail on any issues (bug reports, suggestions, complaints...)
2191 related to the development of the shell should be sent there. If
2192 you want someone to mail you directly, say so. Most patches to zsh
2195 Note that this location has just changed (January 1999), and the
2196 instructions to go with it are slightly different --- in particular,
2197 if you are already subscribed, the instructions about how to
2198 unsubscribe are different.
2200 Please note when reporting bugs that many exist only on certain
2201 architectures, which the developers may not have access to. In
2202 this case debugging information, as detailed as possible, is
2203 particularly welcome.
2205 Two progressively lower volume lists exist, one with messages
2206 concerning the use of zsh,
2208 zsh-users@sunsite.dk
2210 and one just containing announcements: about releases, about major
2211 changes in the shell, or this FAQ, for example,
2213 zsh-announce@sunsite.dk
2215 (posting to the last one is currently restricted).
2217 Note that you should only join one of these lists: people on
2218 zsh-workers receive all the lists, and people on zsh-users will
2219 also receive the announcements list.
2221 The lists are handled by an automated server. The instructions for
2222 zsh-announce and zsh-users are the same as for zsh-workers: just
2223 change zsh-workers to whatever in the following.
2225 To join zsh-workers, send email to
2227 zsh-workers-subscribe@sunsite.dk
2229 (the actual content is unimportant). Replace tt(subscribe) with
2230 tt(unsubscribe) to unsubscribe. The mailing software (tt(ezlm)) has
2231 various bells and whistles: you can retrieve archived messages.
2232 Mail email(zsh-workers-help@sunsite.dk) for detailed information.
2233 Adminstrative matters are best sent to
2234 email(zsh-workers-owner@sunsite.dk). The list maintainer's
2235 real name is email(Karsten Thygesen <karthy@kom.auc.dk>).
2237 An archive of mailings for the last few years can be found at
2238 url(http://www.zsh.org/mla/)(http://www.zsh.org/mla/)
2239 at the main zsh archive in Australia.
2241 Of course, you can also post zsh queries to the Usenet group
2242 comp.unix.shell; if all else fails, you could even e-mail me.
2245 sect(What's on the wish-list?)
2247 The code bears the marks of the ages and many things could be done much
2248 better with a rewrite. A more efficient set of code for
2249 lexing/parsing/execution might also be an advantage. Volunteers are
2250 particularly welcome for these tasks.
2252 Some future possibilities which have been suggested:
2254 it() The shell, in particular the line editor, should support Unicode
2255 characters. Initial support for this appeared in version 4.3;
2256 it is reasonably complete in the line editor but patchy elsewhere
2257 (note this may require the configuration option --enable-multibyte).
2258 it() The parameter code could do with tidying up, maybe with more of the
2259 features made available in ksh93.
2260 it() Configuration files to enable zsh startup files to be created
2261 with the Dotfile Generator.
2262 it() Further improvements in integrating the line editor with shell
2264 it() POSIX compatibility could be improved.
2265 it() Option for glob qualifiers to follow perl syntax (a traditional item).
2269 sect(Did zsh have problems in the year 2000?)
2271 Not that I heard of; it's up to you to be careful with two-digit dates,
2272 though, which are produced by the prompt escapes mytt(%W) and mytt(%D),
2273 and also by the command `tt(print -P)'. Earlier versions of zsh may
2277 nsect(Acknowledgments:)
2279 Thanks to zsh-list, in particular Bart Schaefer, for suggestions
2280 regarding this document. Zsh has been in the hands of archivists Jim
2281 Mattson, Bas de Bakker, Richard Coleman, Zoltan Hidvegi and Andrew
2282 Main, and the mailing list has been run by Peter Gray, Rick Ohnemus,
2283 Richard Coleman and Karsten Thygesen, all of whom deserve thanks. The
2284 world is eternally in the debt of Paul Falstad for inventing zsh in
2285 the first place (though the wizzo extended completion is by Sven
2289 nsect(Copyright Information:)
2291 This document is copyright (C) P.W. Stephenson, 1995, 1996, 1997,
2292 1998, 1999, 2000. This text originates in the U.K. and the author asserts
2293 his moral rights under the Copyrights, Designs and Patents Act, 1988.
2295 Permission is hereby granted, without written agreement and without
2296 license or royalty fees, to use, copy, modify, and distribute this
2297 documentation for any purpose, provided that the above copyright
2298 notice appears in all copies of this documentation. Remember,
2299 however, that this document changes monthly and it may be more useful
2300 to provide a pointer to it rather than the entire text. A suitable
2301 pointer is "information on the Z-shell can be obtained on the World
2302 Wide Web at URL http://sunsite.dk/zsh/".