1 2Archive-Name: unix-faq/shell/zsh 3Last-Modified: 2012/06/15 4Submitted-By: coordinator@zsh.org (Peter Stephenson) 5Posting-Frequency: Monthly 6Copyright: (C) P.W. Stephenson, 1995--2010 (see end of document) 7 8This document contains a list of frequently-asked (or otherwise 9significant) questions concerning the Z-shell, a command interpreter 10for many UNIX systems which is freely available to anyone with FTP 11access. Zsh is among the most powerful freely available Bourne-like 12shell for interactive use. 13 14If you have never heard of `sh', `csh' or `ksh', then you are 15probably better off to start by reading a general introduction to UNIX 16rather than this document. 17 18If you just want to know how to get your hands on the latest version, 19skip to question 1.6; if you want to know what to do with 20insoluble problems, go to 5.2. 21 22Notation: Quotes `like this' are ordinary textual quotation 23marks. Other uses of quotation marks are input to the shell. 24 25Contents: 26Chapter 1: Introducing zsh and how to install it 271.1. Sources of information 281.2. What is it? 291.3. What is it good at? 301.4. On what machines will it run? (Plus important compilation notes) 311.5. What's the latest version? 321.6. Where do I get it? 331.7. I don't have root access: how do I make zsh my login shell? 34 35Chapter 2: How does zsh differ from...? 362.1. sh and ksh? 372.2. csh? 382.3. Why do my csh aliases not work? (Plus other alias pitfalls.) 392.4. tcsh? 402.5. bash? 412.6. Shouldn't zsh be more/less like ksh/(t)csh? 422.7. What is zsh's support for Unicode/UTF-8? 43 44Chapter 3: How to get various things to work 453.1. Why does `$var' where `var="foo bar"' not do what I expect? 463.2. In which startup file do I put...? 473.3. What is the difference between `export' and the ALL_EXPORT option? 483.4. How do I turn off spelling correction/globbing for a single command? 493.5. How do I get the Meta key to work on my xterm? 503.6. How do I automatically display the directory in my xterm title bar? 513.7. How do I make the completion list use eight bit characters? 523.8. Why do the cursor (arrow) keys not work? (And other terminal oddities.) 533.9. Why does my terminal act funny in some way? 543.10. Why does zsh not work in an Emacs shell mode any more? 553.11. Why do my autoloaded functions not autoload [the first time]? 563.12. How does base arithmetic work? 573.13. How do I get a newline in my prompt? 583.14. Why does `bindkey ^a command-name' or 'stty intr ^-' do something funny? 593.15. Why can't I bind \C-s and \C-q any more? 603.16. How do I execute command `foo' within function `foo'? 613.17. Why do history substitutions with single bangs do something funny? 623.18. Why does zsh kill off all my background jobs when I logout? 633.19. How do I list all my history entries? 643.20. How does the alternative loop syntax, e.g. `while {...} {...}' work? 653.21. Why is my history not being saved? 663.22. How do I get a variable's value to be evaluated as another variable? 673.23. How do I prevent the prompt overwriting output when there is no newline? 683.24. What's wrong with cut and paste on my xterm? 693.25. How do I get coloured prompts on my colour xterm? 703.26. Why is my output duplicated with `foo 2>&1 >foo.out | bar'? 713.27. What are these `^' and `~' pattern characters, anyway? 72 73Chapter 4: The mysteries of completion 744.1. What is completion? 754.2. What sorts of things can be completed? 764.3. How does zsh deal with ambiguous completions? 774.4. How do I complete in the middle of words / just what's before the cursor? 784.5. How do I get started with programmable completion? 794.6. Suppose I want to complete all files during a special completion? 80 81Chapter 5: Multibyte input and output 82 835.1. What is multibyte input? 845.2. How does zsh handle multibyte input and output? 855.3. How do I ensure multibyte input and output work on my system? 865.4. How can I input characters that aren't on my keyboard? 87 88Chapter 6: The future of zsh 896.1. What bugs are currently known and unfixed? (Plus recent important changes) 906.2. Where do I report bugs, get more info / who's working on zsh? 916.3. What's on the wish-list? 926.4. Did zsh have problems in the year 2000? 93 94Acknowledgments 95 96Copyright 97--- End of Contents --- 98 99Chapter 1: Introducing zsh and how to install it 100 1011.1: Sources of information 102 103 Information on zsh is available via the World Wide Web. The URL 104 is http://zsh.sourceforge.net/ . 105 The server provides this FAQ and much else and is 106 now maintained by the zsh workers (email zsh-workers@zsh.org). 107 The FAQ is at http://zsh.sourceforge.net/FAQ/ . 108 The site also contains some contributed zsh scripts and functions; 109 we are delighted to add more, or simply links to your own collection. 110 111 This document was originally written in YODL, allowing it to be converted 112 easily into various other formats. The master source file lives at 113 http://zsh.sourceforge.net/FAQ/zshfaq.yo and the plain text version 114 can be found at http://zsh.sourceforge.net/FAQ/zshfaq.txt . 115 116 Another useful source of information is the collection of FAQ articles 117 posted frequently to the Usenet news groups comp.unix.questions, 118 comp.unix.shells and comp.answers with answers to general questions 119 about UNIX. The fifth of the seven articles deals with shells, 120 including zsh, with a brief description of differences. There is 121 also a separate FAQ on shell differences and how to change your 122 shell. Usenet FAQs are available via FTP from rtfm.mit.edu and 123 mirrors and also on the World Wide Web; see 124 125 USA http://www.cis.ohio-state.edu/hypertext/faq/usenet/top.html 126 UK http://www.lib.ox.ac.uk/internet/news/faq/comp.unix.shell.html 127 Netherlands http://www.cs.uu.nl/wais/html/na-dir/unix-faq/shell/.html 128 129 You can also get it via email by emailing mail-server@rtfm.mit.edu 130 with, in the body of the message, `send faqs/unix-faq/shell/zsh'. 131 132 The latest version of this FAQ is also available directly from any 133 of the zsh archive sites listed in question 1.6. 134 135 I have put together a user guide to complement the manual by 136 explaining the most useful features of zsh in a more easy to read way. 137 This can be found at the zsh web site: 138 http://zsh.sourceforge.net/Guide/ 139 140 (As a method of reading the following in Emacs, you can type \M-2 141 \C-x $ to make all the indented text vanish, then \M-0 \C-x $ 142 when you are on the title you want.) 143 144 For any more eclectic information, you should contact the mailing 145 list: see question 5.2. 146 1471.2: What is it? 148 149 Zsh is a UNIX command interpreter (shell) which of the standard 150 shells most resembles the Korn shell (ksh); its compatibility with 151 the 1988 Korn shell has been gradually increasing. It includes 152 enhancements of many types, notably in the command-line editor, 153 options for customising its behaviour, filename globbing, features 154 to make C-shell (csh) users feel more at home and extra features 155 drawn from tcsh (another `custom' shell). 156 157 It was written by Paul Falstad when a student at Princeton; however, 158 Paul doesn't maintain it any more and enquiries should be sent to 159 the mailing list (see question 5.2). Zsh is distributed under a 160 standard Berkeley style copyright. 161 162 For more information, the files Doc/intro.txt or Doc/intro.troff 163 included with the source distribution are highly recommended. A list 164 of features is given in FEATURES, also with the source. 165 1661.3: What is it good at? 167 168 Here are some things that zsh is particularly good at. No claim of 169 exclusivity is made, especially as shells copy one another, though 170 in the areas of command line editing and globbing zsh is well ahead 171 of the competition. I am not aware of a major interactive feature 172 in any other freely-available shell which zsh does not also have 173 (except smallness). 174 175 o Command line editing: 176 177 o programmable completion: incorporates the ability to use the 178 full power of zsh's globbing and shell programming features, 179 o multi-line commands editable as a single buffer (even files!), 180 o variable editing (vared), 181 o command buffer stack, 182 o print text straight into the buffer for immediate editing (print -z), 183 o execution of unbound commands, 184 o menu completion in two flavours, 185 o variable, editing function and option name completion, 186 o inline expansion of variables and history commands. 187 188 o Globbing --- extremely powerful, including: 189 190 o recursive globbing (cf. find), 191 o file attribute qualifiers (size, type, etc. also cf. find), 192 o full alternation and negation of patterns. 193 194 o Handling of multiple redirections (simpler than tee). 195 o Large number of options for tailoring. 196 o Path expansion (=foo -> /usr/bin/foo). 197 o Adaptable messages for spelling, watch, time as well as prompt 198 (including conditional expressions). 199 o Named directories. 200 o Comprehensive integer and floating point arithmetic. 201 o Manipulation of arrays (including reverse subscripting). 202 o Associative arrays (key-to-value hashes) 203 o Spelling correction. 204 2051.4: On what machines will it run? 206 207 From version 3.0, zsh uses GNU autoconf as the installation 208 mechanism. This considerably increases flexibility over the old 209 `buildzsh' mechanism. Consequently, zsh should compile and run on 210 any modern version of UNIX, and a great many not-so-modern versions 211 too. The file MACHINES in the distribution has more details. 212 213 There used to be separate ports for Windows and OS/2, but these 214 are rather out of date and hard to get; however, zsh exists for 215 the Cygwin environment. See further notes below. 216 217 If you need to change something to support a new machine, it would be 218 appreciated if you could add any necessary preprocessor code and 219 alter configure.in and acconfig.h to configure zsh automatically, 220 then send the required context diffs to the list (see question 221 5.2). Please make sure you have the latest version first. 222 223 To get it to work, retrieve the source distribution (see question 224 1.6), un-gzip it, un-tar it and read the INSTALL file in the top 225 directory. Also read the MACHINES file for up-to-date 226 information on compilation on certain architectures. 227 228 *Note for users of nawk* (The following information comes from Zoltan 229 Hidvegi): On some systems nawk is broken and produces an incorrect 230 signames.h file. This makes the signals code unusable. This often happens 231 on Ultrix, HP-UX, IRIX (?). Install gawk if you experience such problems. 232 2331.5: What's the latest version? 234 235 Zsh 5.0.5 is the latest production version. For details of all the 236 changes, see the NEWS file in the source distribution. 237 238 A beta of the next version is sometimes available. Development of zsh is 239 patch by patch, with each intermediate version publicly available. Note 240 that this `open' development system does mean bugs are sometimes 241 introduced into the most recent archived version. These are usually 242 fixed quickly. If you are really interested in getting the latest 243 improvements, and less worried about providing a stable environment, 244 development versions are uploaded quite frequently to the archive in the 245 development subdirectory. 246 247 Note also that as the shell changes, it may become incompatible with 248 older versions; see the end of question 5.1 for a partial list. 249 Changes of this kind are almost always forced by an awkward or 250 unnecessary feature in the original design (as perceived by current 251 users), or to enhance compatibility with other Bourne shell 252 derivatives, or (mostly in the 3.0 series) to provide POSIX compliancy. 253 2541.6: Where do I get it? 255 256 The coordinator of development is currently me; the alias 257 coordinator@zsh.org can be used to contact whoever is in the hot 258 seat. The following are known mirrors (kept frequently up to date); the 259 first is the official archive site, currently in Australia. All are 260 available by anonymous FTP. The major sites keep test versions in the 261 `testing' subdirectory: such up-to-the-minute development versions should 262 only be retrieved if you actually plan to help test the latest version of 263 the shell. The following list also appears on the WWW at 264 http://www.zsh.org/ . 265 266Primary site: 267ftp://ftp.zsh.org/pub/ 268http://www.zsh.org/pub/ 269 270Australia: 271ftp://ftp.zsh.org/pub/ 272http://www.zsh.org/pub/ 273http://mirror.dejanseo.com.au/pub/zsh/ 274 275Hungary: 276ftp://ftp.cs.elte.hu/pub/zsh/ 277http://www.cs.elte.hu/pub/zsh/ 278 279 A Windows port was created by Amol Deshpandem based on 3.0.5 (which 280 is now rather old). This has now been restored and can be found at 281 http://zsh-nt.sourceforge.net/. 282 283 All recent releases of zsh compile under Cygwin, a freely available 284 UNIX-style environment for the Win32 API, and a pre-compiled version of 285 zsh can be downloaded by the Cygwin installer. You can find information 286 about this at http://www.cygwin.com/. 287 Please email zsh-workers@zsh.org if you have information about 288 other ports. 289 290 Starting from mid-October 1997, there is an archive of patches sent 291 to the maintainers' mailing list. Note that these may not all be 292 added to the shell, and some may already have been; you simply have 293 to search for something you might want which is not in the version 294 you have. Also, there may be some prerequisites earlier in the 295 archive. It can be found on the zsh WWW pages (as described in 296 1.1) at: 297 298 http://zsh.sourceforge.net/Patches/ 299 3001.7: I don't have root access: how do I make zsh my login shell? 301 302 Unfortunately, on many machines you can't use `chsh' to change your 303 shell unless the name of the shell is contained in /etc/shells, so if 304 you have your own copy of zsh you need some sleight-of-hand to use it 305 when you log on. (Simply typing `zsh' is not really a solution since 306 you still have your original login shell waiting for when you exit.) 307 308 The basic idea is to use `exec <zsh-path>' to replace the current 309 shell with zsh. Often you can do this in a login file such as .profile 310 (if your shell is sh or ksh) or .login (if it's csh). Make sure you 311 have some way of altering the file (e.g. via FTP) before you try this as 312 `exec' is often rather unforgiving. 313 314 If you have zsh in a subdirectory `bin' of your home directory, 315 put this in .profile: 316 317 [ -f $HOME/bin/zsh ] && exec $HOME/bin/zsh -l 318 319 or if your login shell is csh or tcsh, put this in .login: 320 321 if ( -f ~/bin/zsh ) exec ~/bin/zsh -l 322 323 (in each case the `-l' tells zsh it is a login shell). 324 325 If you want to check this works before committing yourself to it, 326 you can make the login shell ask whether to exec zsh. The following 327 work for Bourne-like shells: 328 329 [ -f $HOME/bin/zsh ] && { 330 echo "Type Y to run zsh: \c" 331 read line 332 [ "$line" = Y ] && exec $HOME/bin/zsh -l 333 } 334 335 and for C-shell-like shells: 336 337 if ( -f ~/bin/zsh ) then 338 echo -n "Type Y to run zsh: " 339 if ( "$<" == Y ) exec ~/bin/zsh -l 340 endif 341 342 It's not a good idea to put this (even without the -l) into .cshrc, 343 at least without some tests on what the csh is supposed to be doing, 344 as that will cause _every_ instance of csh to turn into a zsh and 345 will cause csh scripts (yes, unfortunately some people write these) 346 which do not call `csh -f' to fail. If you want to tell xterm to 347 run zsh, change the SHELL environment variable to the full path of 348 zsh at the same time as you exec zsh (in fact, this is sensible for 349 consistency even if you aren't using xterm). If you have to exec 350 zsh from your .cshrc, a minimum safety check is `if ($?prompt) exec 351 zsh'. 352 353 If you like your login shell to appear in the process list as `-zsh', 354 you can link `zsh' to `-zsh' (e.g. by `ln -s ~/bin/zsh 355 ~/bin/-zsh') and change the exec to `exec -zsh'. (Make sure 356 `-zsh' is in your path.) This has the same effect as the `-l' 357 option. 358 359 Footnote: if you DO have root access, make sure zsh goes in 360 /etc/shells on all appropriate machines, including NIS clients, or you 361 may have problems with FTP to that machine. 362 363Chapter 2: How does zsh differ from...? 364 365As has already been mentioned, zsh is most similar to ksh, while many 366of the additions are to please csh users. Here are some more detailed 367notes. See also the article `UNIX shell differences and how to change 368your shell' posted frequently to the USENET group comp.unix.shell. 369 3702.1: Differences from sh and ksh 371 372 Most features of ksh (and hence also of sh) are implemented in zsh; 373 problems can arise because the implementation is slightly different. 374 Note also that not all ksh's are the same either. I have based this 375 on the 11/16/88f version of ksh; differences from ksh93 will be more 376 substantial. 377 378 As a summary of the status: 379 380 1) because of all the options it is not safe to assume a general 381 zsh run by a user will behave as if sh or ksh compatible; 382 2) invoking zsh as sh or ksh (or if either is a symbolic link to 383 zsh) sets appropriate options and improves compatibility (from 384 within zsh itself, calling `ARGV0=sh zsh' will also work); 385 3) from version 3.0 onward the degree of compatibility with sh 386 under these circumstances is very high: zsh can now be used 387 with GNU configure or perl's Configure, for example; 388 4) the degree of compatibility with ksh is also high, but a few 389 things are missing: for example the more sophisticated 390 pattern-matching expressions are different for versions before 391 3.1.3 --- see the detailed list below; 392 5) also from 3.0, the command `emulate' is available: `emulate 393 ksh' and `emulate sh' set various options as well as changing the 394 effect of single-letter option flags as if the shell had been 395 invoked with the appropriate name. Including the command 396 `emulate sh; setopt localoptions' in a shell function will 397 turn on sh emulation for that function only. In version 4 (and in 398 3.0.6 through 8), this can be abbreviated as `emulate -L sh'. 399 400 The classic difference is word splitting, discussed in question 3.1; 401 this catches out very many beginning zsh users. As explained there, 402 this is actually a bug in every other shell. The answer is to set 403 SH_WORD_SPLIT for backward compatibility. The next most classic 404 difference is that unmatched glob patterns cause the command to abort; 405 set NO_NOMATCH for those. 406 407 Here is a list of various options which will increase ksh 408 compatibility, though maybe decrease zsh's abilities: see the manual 409 entries for GLOB_SUBST, IGNORE_BRACES (though brace expansion occurs 410 in some versions of ksh), KSH_ARRAYS, KSH_GLOB, KSH_OPTION_PRINT, 411 LOCAL_OPTIONS, NO_BAD_PATTERN, NO_BANG_HIST, NO_EQUALS, NO_HUP, 412 NO_NOMATCH, NO_RCS, NO_SHORT_LOOPS, PROMPT_SUBST, RM_STAR_SILENT, 413 POSIX_ALIASES, POSIX_BUILTINS, POSIX_IDENTIFIERS, 414 SH_FILE_EXPANSION, SH_GLOB, SH_OPTION_LETTERS, 415 SH_WORD_SPLIT (see question 3.1) and SINGLE_LINE_ZLE. 416 Note that you can also disable any built-in commands which get in 417 your way. If invoked as `ksh', the shell will try to set suitable 418 options. 419 420 Here are some differences from ksh which might prove significant for 421 ksh programmers, some of which may be interpreted as bugs; there 422 must be more. Note that this list is deliberately rather full and 423 that most of the items are fairly minor. Those marked `*' perform 424 in a ksh-like manner if the shell is invoked with the name `ksh', or 425 if `emulate ksh' is in effect. Capitalised words with underlines 426 refer to shell options. 427 428 o Syntax: 429 430 o * Shell word splitting: see question 3.1. 431 o * Arrays are (by default) more csh-like than ksh-like: 432 subscripts start at 1, not 0; array[0] refers to array[1]; 433 `$array' refers to the whole array, not $array[0]; 434 braces are unnecessary: $a[1] == ${a[1]}, etc. 435 Set the KSH_ARRAYS option for compatibility. 436 o Furthermore, individual elements of arrays in zsh are always 437 strings, not separate parameters. This means, for example, you 438 can't `unset' an array element in zsh as you can in ksh; you 439 can only set it to the empty string, or shorten the array. 440 (You can unset elements of associative arrays in zsh because 441 those are a completely different type of object.) 442 o Coprocesses are established by `coproc'; `|&' behaves like 443 csh. Handling of coprocess file descriptors is also different. 444 o In `cmd1 && cmd2 &', only `cmd2' instead of the whole 445 expression is run in the background in zsh. The manual implies 446 this is a bug. Use `{ cmd1 && cmd2 } &' as a workaround. 447 448 o Command line substitutions, globbing etc.: 449 450 o * Failure to match a globbing pattern causes an error (use 451 NO_NOMATCH). 452 o * The results of parameter substitutions are treated as plain text: 453 `foo="*"; print $foo' prints all files in ksh but `*' in zsh 454 (use GLOB_SUBST). 455 o * $PSn do not do parameter substitution by default (use PROMPT_SUBST). 456 o * Standard globbing does not allow ksh-style `pattern-lists'. 457 Equivalents: 458 459---------------------------------------------------------------------- 460 ksh zsh Meaning 461 ------ ------ --------- 462 !(foo) ^foo Anything but foo. 463 or foo1~foo2 Anything matching foo1 but foo2[1]. 464@(foo1|foo2|...) (foo1|foo2|...) One of foo1 or foo2 or ... 465 ?(foo) (foo|) Zero or one occurrences of foo. 466 *(foo) (foo)# Zero or more occurrences of foo. 467 +(foo) (foo)## One or more occurrences of foo. 468---------------------------------------------------------------------- 469 470 The `^', `~' and `#' (but not `|')forms require EXTENDED_GLOB. 471 From version 3.1.3, the ksh forms are fully supported when the 472 option KSH_GLOB is in effect; for previous versions you 473 must use the table above. 474 475 [1] See question 3.27 for more on the mysteries of 476 `~' and `^'. 477 o Unquoted assignments do file expansion after `:'s (intended for 478 PATHs). 479 o * `typeset' and `integer' have special behaviour for 480 assignments in ksh, but not in zsh. For example, this doesn't 481 work in zsh: 482 483 integer k=$(wc -l ~/.zshrc) 484 485 because the return value from wc includes leading 486 whitespace which causes wordsplitting. Ksh handles the 487 assignment specially as a single word. 488 489 o Command execution: 490 491 o * There is no $ENV variable (use /etc/zshrc, ~/.zshrc; 492 note also $ZDOTDIR). 493 o * $PATH is not searched for commands specified 494 at invocation without -c. 495 496 o Aliases and functions: 497 498 o The order in which aliases and functions are defined is significant: 499 function definitions with () expand aliases -- see question 2.3. 500 o Aliases and functions cannot be exported. 501 o There are no tracked aliases: command hashing replaces these. 502 o The use of aliases for key bindings is replaced by `bindkey'. 503 o * Options are not local to functions (use LOCAL_OPTIONS; note this 504 may always be unset locally to propagate options settings from a 505 function to the calling level). 506 o Functions defined with `function funcname { body }' behave the 507 same way as those defined with `funcname () { body }'. In ksh, 508 the former behave as if the body were read from a file with `.', 509 and only the latter behave as true functions. 510 511 o Traps and signals: 512 513 o * Traps are not local to functions. The option LOCAL_TRAPS is 514 available from 3.1.6. 515 o TRAPERR has become TRAPZERR (this was forced by UNICOS which 516 has SIGERR). 517 518 o Editing: 519 520 o The options gmacs, viraw are not supported. 521 Use bindkey to change the editing behaviour: `set -o {emacs,vi}' 522 becomes `bindkey -{e,v}', although `set -o emacs' and `set -o vi' 523 are supported for compatibility; for gmacs, go to emacs mode and 524 use `bindkey \^t gosmacs-transpose-characters'. 525 o The `keyword' option does not exist and `-k' is instead 526 interactivecomments. (`keyword' is not in recent versions 527 of ksh either.) 528 o * Management of histories in multiple shells is different: 529 the history list is not saved and restored after each command. 530 The option SHARE_HISTORY appeared in 3.1.6 and is set in ksh 531 compatibility mode to remedy this. 532 o `\' does not escape editing chars (use `^V'). 533 o Not all ksh bindings are set (e.g. `<ESC>#'; try `<ESC>q'). 534 o * `#' in an interactive shell is not treated as a comment by 535 default. 536 o In vi command mode the keys "k" and "j" move the cursor to the 537 end of the line. To move the cursor to the start instead, use 538 539 bindkey -M vicmd 'k' vi-up-line-or-history 540 bindkey -M vicmd 'j' vi-down-line-or-history 541 542 o Built-in commands: 543 544 o Some built-ins (r, autoload, history, integer ...) 545 were aliases in ksh. 546 o There is no built-in command newgrp: use e.g. `alias 547 newgrp="exec newgrp"' 548 o `jobs' has no `-n' flag. 549 550 o Other idiosyncrasies: 551 552 o `select' always redisplays the list of selections on each loop. 553 5542.2: Similarities with csh 555 556 Although certain features aim to ease the withdrawal symptoms of csh 557 (ab)users, the syntax is in general rather different and you should 558 certainly not try to run scripts without modification. The c2z script 559 is provided with the source (in Misc/c2z) to help convert .cshrc 560 and .login files; see also the next question concerning aliases, 561 particularly those with arguments. 562 563 Csh-compatibility additions include: 564 565 o logout, rehash, source, (un)limit built-in commands. 566 o *rc file for interactive shells. 567 o Directory stacks. 568 o cshjunkie*, ignoreeof options. 569 o The CSH_NULL_GLOB option. 570 o >&, |& etc. redirection. 571 (Note that `>file 2>&1' is the standard Bourne shell command for 572 csh's `>&file'.) 573 o foreach ... loops; alternative syntax for other loops. 574 o Alternative syntax `if ( ... ) ...', though this still doesn't 575 work like csh: it expects a command in the parentheses. Also 576 `for', `which'. 577 o $PROMPT as well as $PS1, $status as well as $?, 578 $#argv as well as $#, .... 579 o Escape sequences via % for prompts. 580 o Special array variables $PATH etc. are colon-separated, $path 581 are arrays. 582 o !-type history (which may be turned off via `setopt 583 nobanghist'). 584 o Arrays have csh-like features (see under 2.1). 585 5862.3: Why do my csh aliases not work? (Plus other alias pitfalls.) 587 588 First of all, check you are using the syntax 589 590 alias newcmd='list of commands' 591 592 and not 593 594 alias newcmd 'list of commands' 595 596 which won't work. (It tells you if `newcmd' and `list of commands' are 597 already defined as aliases.) 598 599 Otherwise, your aliases probably contain references to the command 600 line of the form `\!*', etc. Zsh does not handle this behaviour as it 601 has shell functions which provide a way of solving this problem more 602 consistent with other forms of argument handling. For example, the 603 csh alias 604 605 alias cd 'cd \!*; echo $cwd' 606 607 can be replaced by the zsh function, 608 609 cd() { builtin cd "$@"; echo $PWD; } 610 611 (the `builtin' tells zsh to use its own `cd', avoiding an infinite loop) 612 or, perhaps better, 613 614 cd() { builtin cd "$@"; print -D $PWD; } 615 616 (which converts your home directory to a ~). In fact, this problem is 617 better solved by defining the special function chpwd() (see the manual). 618 Note also that the `;' at the end of the function is optional in zsh, 619 but not in ksh or sh (for sh's where it exists). 620 621 Here is Bart Schaefer's guide to converting csh aliases for zsh. 622 623 1) If the csh alias references "parameters" (\!:1, \!* etc.), 624 then in zsh you need a function (referencing $1, $* etc.). 625 Otherwise, you can use a zsh alias. 626 627 2) If you use a zsh function, you need to refer _at_least_ to 628 $* in the body (inside the { }). Parameters don't magically 629 appear inside the { } the way they get appended to an alias. 630 631 3) If the csh alias references its own name (alias rm "rm -i"), 632 then in a zsh function you need the "command" or "builtin" keyword 633 (function rm() { command rm -i "$@" }), but in a zsh alias 634 you don't (alias rm="rm -i"). 635 636 4) If you have aliases that refer to each other (alias ls "ls -C"; 637 alias lf "ls -F" ==> lf == ls -C -F) then you must either: 638 639 o convert all of them to zsh functions; or 640 o after converting, be sure your .zshrc defines all of your 641 aliases before it defines any of your functions. 642 643 Those first four are all you really need, but here are four more for 644 heavy csh alias junkies: 645 646 5) Mapping from csh alias "parameter referencing" into zsh function 647 (assuming SH_WORD_SPLIT and KSH_ARRAYS are NOT set in zsh): 648 649 csh zsh 650 ===== ========== 651 \!* $* (or $argv) 652 \!^ $1 (or $argv[1]) 653 \!:1 $1 654 \!:2 $2 (or $argv[2], etc.) 655 \!$ $*[$#] (or $argv[$#], or $*[-1]) 656 \!:1-4 $*[1,4] 657 \!:1- $*[1,$#-1] (or $*[1,-2]) 658 \!^- $*[1,$#-1] 659 \!*:q "$@" 660 \!*:x $=* ($*:x doesn't work (yet)) 661 662 6) Remember that it is NOT a syntax error in a zsh function to 663 refer to a position ($1, $2, etc.) greater than the number of 664 parameters. (E.g., in a csh alias, a reference to \!:5 will 665 cause an error if 4 or fewer arguments are given; in a zsh 666 function, $5 is the empty string if there are 4 or fewer 667 parameters.) 668 669 7) To begin a zsh alias with a - (dash, hyphen) character, use 670 `alias --': 671 672 csh zsh 673 =============== ================== 674 alias - "fg %-" alias -- -="fg %-" 675 676 8) Stay away from `alias -g' in zsh until you REALLY know what 677 you're doing. 678 679 There is one other serious problem with aliases: consider 680 681 alias l='/bin/ls -F' 682 l() { /bin/ls -la "$@" | more } 683 684 `l' in the function definition is in command position and is expanded 685 as an alias, defining `/bin/ls' and `-F' as functions which call 686 `/bin/ls', which gets a bit recursive. This can be avoided if you use 687 `function' to define a function, which doesn't expand aliases. It is 688 possible to argue for extra warnings somewhere in this mess. 689 690 Bart Schaefer's rule is: Define first those aliases you expect to 691 use in the body of a function, but define the function first if the 692 alias has the same name as the function. 693 694 If you aware of the problem, you can always escape part or all of the 695 name of the function: 696 697 'l'() { /bin/ls -la "$@" | more } 698 699 Adding the quotes has no effect on the function definition, but 700 suppresses alias expansion for the function name. Hence this is 701 guaranteed to be safe---unless you are in the habit of defining 702 aliases for expressions such as 'l', which is valid, but probably 703 confusing. 704 7052.4: Similarities with tcsh 706 707 (The sections on csh apply too, of course.) Certain features have 708 been borrowed from tcsh, including $watch, run-help, $savehist, 709 periodic commands etc., extended prompts, sched and which built-ins. 710 Programmable completion was inspired by, but is entirely different to, 711 tcsh's `complete'. (There is a perl script called lete2ctl in the 712 Misc directory of the source distribution to convert `complete' to `compctl' 713 statements.) This list is not definitive: some features have gone in 714 the other direction. 715 716 If you're missing the editor function run-fg-editor, try something 717 with `bindkey -s' (which binds a string to a keystroke), e.g. 718 719 bindkey -s '^z' '\eqfg %$EDITOR:t\n' 720 721 which pushes the current line onto the stack and tries to bring a job 722 with the basename of your editor into the foreground. `bindkey -s' 723 allows limitless possibilities along these lines. You can execute 724 any command in the middle of editing a line in the same way, 725 corresponding to tcsh's `-c' option: 726 727 bindkey -s '^p' '\eqpwd\n' 728 729 In both these examples, the `\eq' saves the current input line to 730 be restored after the command runs; a better effect with multiline 731 buffers is achieved if you also have 732 733 bindkey '\eq' push-input 734 735 to save the entire buffer. In version 4 and recent versions of zsh 3.1, 736 you have the following more sophisticated option, 737 738 run-fg-editor() { 739 zle push-input 740 BUFFER="fg %$EDITOR:t" 741 zle accept-line 742 } 743 zle -N run-fg-editor 744 745 and can now bind run-fg-editor just like any other editor function. 746 7472.5: Similarities with bash 748 749 The Bourne-Again Shell, bash, is another enhanced Bourne-like shell; 750 the most obvious difference from zsh is that it does not attempt to 751 emulate the Korn shell. Since both shells are under active 752 development it is probably not sensible to be too specific here. 753 Broadly, bash has paid more attention to standards compliancy 754 (i.e. POSIX) for longer, and has so far avoided the more abstruse 755 interactive features (programmable completion, etc.) that zsh has. 756 757 In recent years there has been a certain amount of crossover in the 758 extensions, however. Zsh (as of 3.1.6) has bash's `${var/old/new}' 759 feature for replacing the text old with the text new in the 760 parameter $var. Note one difference here: while both shells 761 implement the syntax `${var/#old/new}' and `${var/%old/new}' for 762 anchoring the match of old to the start or end of the parameter text, 763 respectively, in zsh you can't put the `#' or `%' inside a 764 parameter: in other words `{var/$old/new}' where old begins with 765 a `#' treats that as an ordinary character in zsh, unlike bash. To 766 do this sort of thing in zsh you can use (from 3.1.7) the new syntax 767 for anchors in any pattern, `(#s)' to match the start of a string, 768 and `(#e)' to match the end. These require the option 769 EXTENDED_GLOB to be set. 770 7712.6: Shouldn't zsh be more/less like ksh/(t)csh? 772 773 People often ask why zsh has all these `unnecessary' csh-like features, 774 or alternatively why zsh doesn't understand more csh syntax. This is 775 far from a definitive answer and the debate will no doubt continue. 776 777 Paul's object in writing zsh was to produce a ksh-like shell which 778 would have features familiar to csh users. For a long time, csh was 779 the preferred interactive shell and there is a strong resistance to 780 changing to something unfamiliar, hence the additional syntax and 781 CSH_JUNKIE options. This argument still holds. On the other hand, 782 the arguments for having what is close to a plug-in replacement for ksh 783 are, if anything, even more powerful: the deficiencies of csh as a 784 programming language are well known (look in any Usenet FAQ archive, e.g. 785 http://www.cis.ohio-state.edu/hypertext/faq/usenet/unix-faq/\ 786 shell/csh-whynot/faq.html 787 if you are in any doubt) and zsh is able to run many standard 788 scripts such as /etc/rc. 789 790 Of course, this makes zsh rather large and feature-ridden so that it 791 seems to appeal mainly to hackers. The only answer, perhaps not 792 entirely satisfactory, is that you have to ignore the bits you don't 793 want. The introduction of loadable in modules in version 3.1 should 794 help. 795 7962.7: What is zsh's support for Unicode/UTF-8? 797 798 `Unicode', or UCS for Universal Character Set, is the modern way 799 of specifying character sets. It replaces a large number of ad hoc 800 ways of supporting character sets beyond ASCII. `UTF-8' is an 801 encoding of Unicode that is particularly natural on Unix-like systems. 802 803 The production branch of zsh, 4.2, has very limited support: 804 the built-in printf command supports "\u" and "\U" escapes 805 to output arbitrary Unicode characters; ZLE (the Zsh Line Editor) has 806 no concept of character encodings, and is confused by multi-octet 807 encodings. 808 809 However, the 4.3 branch has much better support, and furthermore this 810 is now fairly stable. (Only a few minor areas need fixing before 811 this becomes a production release.) This is discussed more 812 fully below, see `Multibyte input and output'. 813 814Chapter 3: How to get various things to work 815 8163.1: Why does `$var' where `var="foo bar"' not do what I expect? 817 818 In most Bourne-shell derivatives, multiple-word variables such as 819 820 var="foo bar" 821 822 are split into words when passed to a command or used in a `for foo in 823 $var' loop. By default, zsh does not have that behaviour: the 824 variable remains intact. (This is not a bug! See below.) The option 825 SH_WORD_SPLIT exists to provide compatibility. 826 827 For example, defining the function args to show the number of its 828 arguments: 829 830 args() { echo $#; } 831 832 and with our definition of `var', 833 834 args $var 835 836 produces the output `1'. After 837 838 setopt shwordsplit 839 840 the same function produces the output `2', as with sh and ksh. 841 842 Unless you need strict sh/ksh compatibility, you should ask yourself 843 whether you really want this behaviour, as it can produce unexpected 844 effects for variables with entirely innocuous embedded spaces. This 845 can cause horrendous quoting problems when invoking scripts from 846 other shells. The natural way to produce word-splitting behaviour 847 in zsh is via arrays. For example, 848 849 set -A array one two three twenty 850 851 (or 852 853 array=(one two three twenty) 854 855 if you prefer), followed by 856 857 args $array 858 859 produces the output `4', regardless of the setting of SH_WORD_SPLIT. 860 Arrays are also much more versatile than single strings. Probably 861 if this mechanism had always been available there would never have 862 been automatic word splitting in scalars, which is a sort of 863 uncontrollable poor man's array. 864 865 Note that this happens regardless of the value of the internal field 866 separator, $IFS; in other words, with `IFS=:; foo=a:b; args $foo' 867 you get the answer 1. 868 869 Other ways of causing word splitting include a judicious use of 870 `eval': 871 872 sentence="Longtemps, je me suis couch\\'e de bonne heure." 873 eval "words=($sentence)" 874 875 after which $words is an array with the words of $sentence (note 876 characters special to the shell, such as the `'' in this example, 877 must already be quoted), or, less standard but more reliable, 878 turning on SH_WORD_SPLIT for one variable only: 879 880 args ${=sentence} 881 882 always returns 8 with the above definition of `args'. (In older 883 versions of zsh, ${=foo} toggled SH_WORD_SPLIT; now it forces it on.) 884 885 Note also the "$@" method of word splitting is always available in zsh 886 functions and scripts (though strictly this does array splitting, not 887 word splitting). This is more portable than the $*, since it 888 will work regardless of the SH_WORD_SPLIT setting; the other 889 difference is that $* removes empty arguments from the array. 890 You can fix the first half of that objection by using ${==*}, 891 which turns off SH_WORD_SPLIT for the duration of the expansion. 892 893 SH_WORD_SPLIT is set when zsh is invoked with the names `ksh' or `sh', 894 or (entirely equivalent) when `emulate ksh' or `emulate sh' is in 895 effect. 896 897 There is one other effect of word splitting which differs between ksh 898 and zsh. In ksh, the builtin commands that declare parameters such 899 as typeset and export force word-splitting not to take place 900 after on an assignment argument: 901 902 typeset param=`echo foo bar` 903 904 in ksh will create a parameter with value `foo bar', but in zsh will 905 create a parameter param with value foo and a parameter bar 906 whose value is empty. Contrast this with a normal assignment (no 907 typeset or other command in front), which never causes a word split 908 unless you have GLOB_ASSIGN set. From zsh version 4.0.2 the option 909 KSH_TYPESET, set automatically in compatibility mode, fixes this 910 problem. Note that in bash this behaviour occurs with all arguments that 911 look like assignments, whatever the command name; to get this behaviour 912 in zsh you have to set the option MAGIC_EQUAL_SUBST. 913 9143.2: In which startup file do I put...? 915 916 When zsh starts up, there are four files you can change which it will 917 run under various circumstances: .zshenv, .zprofile, .zshrc 918 and .zlogin. They are usually in your home directory, but the 919 variable $ZDOTDIR may be set to alter that. Here are a few simple 920 hints about how to use them. There are also files which the system 921 administrator can set for all shells; you can avoid running all except 922 /etc/zshenv by starting zsh with the -f option --- for this 923 reason it is important for administrators to make sure /etc/zshenv 924 is as brief as possible. 925 926 The order in which the four files are searched (none of them _need_ 927 to exist) is the one just given. However, .zprofile and .zlogin 928 are only run when the shell is a login shell --- when you first login, 929 of course, and whenever you start zsh with the -l option. All 930 login shells are interactive. The order is the only difference 931 between those; you should decide whether you need things set before or 932 after .zshrc. These files are a good place to set environment 933 variables (i.e. `export' commands), since they are passed on to 934 all shells without you having to set them again, and also to check 935 that your terminal is set up properly (except that if you want to 936 change settings for terminal emulator windows like xterm you will 937 need to put those in .zshrc, since usually you do not get a login 938 shell here). 939 940 The only file you can alter which is started with every zsh (unless 941 you use the -f option) is .zshenv, so this is a good place to put 942 things you want even if the shell is non-interactive: options for 943 changing the syntax, like EXTENDED_GLOB, any changes to set with 944 `limit', any more variables you want to make sure are set as for 945 example $fpath to find functions. You almost certainly do not 946 want .zshenv to produce any output. Some people prefer not to 947 use .zshenv for setting options, as this affects scripts; but 948 making zsh scripts portable usually requires special handling anyway. 949 950 Finally, .zshrc is run for every interactive shell; that includes 951 login shells, but also any other time you start up a shell, such as 952 simply by typing `zsh' or opening a new terminal emulator window. 953 This file is the place to change the editing behaviour via options or 954 `bindkey', control how your history is saved, set aliases unless 955 you want to use them in scripts too, and for any other clutter which 956 can't be exported but you only use when interacting directly with the 957 shell. You probably don't want .zshrc to produce output, either, 958 since there are occasions when this can be a problem, such as when 959 using `rsh' from another host. See 3.21 for what to put in .zshrc 960 to save your history. 961 9623.3: What is the difference between `export' and the ALL_EXPORT option? 963 964 Normally, you would put a variable into the environment by using 965 `export var'. The command `setopt allexport' causes all 966 variables which are subsequently set (N.B. not all the ones which 967 already exist) to be put into the environment. 968 969 This may seem a useful shorthand, but in practice it can have 970 unhelpful side effects: 971 972 1) Since every variable is in the environment as well as remembered 973 by the shell, the memory for it needs to be allocated twice. 974 This is bigger as well as slower. 975 2) It really is *every* variable which is exported, even loop 976 variables in `for' loops. This is probably a waste. 977 3) An arbitrary variable created by the user might have a special 978 meaning to a command. Since all shell variables are visible to 979 commands, there is no protection against this. 980 981 For these reasons it is usually best to avoid ALL_EXPORT unless you 982 have a specific use for it. One safe use is to set it before 983 creating a list of variables in an initialisation file, then unset 984 it immediately afterwards. Only those variables will be automatically 985 exported. 986 9873.4: How do I turn off spelling correction/globbing for a single command? 988 989 In the first case, you presumably have `setopt correctall' in an 990 initialisation file, so that zsh checks the spelling of each word in 991 the command line. You probably do not want this behaviour for 992 commands which do not operate on existing files. 993 994 The answer is to alias the offending command to itself with 995 `nocorrect' stuck on the front, e.g. 996 997 alias mkdir='nocorrect mkdir' 998 999 To turn off globbing, the rationale is identical: 1000 1001 alias mkdir='noglob mkdir' 1002 1003 You can have both nocorrect and noglob, if you like, but the 1004 nocorrect must come first, since it is needed by the line editor, 1005 while noglob is only handled when the command is examined. 1006 1007 Note also that a shell function won't work: the no... directives must 1008 be expanded before the rest of the command line is parsed. 1009 10103.5: How do I get the Meta key to work on my xterm? 1011 1012 The Meta key isn't present on a lot of keyboards, but on some 1013 the Alt key has the same effect. If a character is typed on the 1014 keyboard while the Meta key is held down, the characters is sent 1015 as terminal input with its eighth bit set. For example, ASCII 1016 `A', hex 65, becomes hex E5. This is sometimes used to provide 1017 extra editing commands. 1018 1019 As stated in the manual, zsh needs to be told about the Meta key by 1020 using `bindkey -me' or `bindkey -mv' in your .zshrc or on the 1021 command line. You probably also need to tell the terminal driver to 1022 allow the `Meta' bit of the character through; `stty pass8' is the 1023 usual incantation. Sample .zshrc entry: 1024 1025 [[ $TERM = "xterm" ]] && stty pass8 && bindkey -me 1026 1027 or, on SYSVR4-ish systems without pass8, 1028 1029 [[ $TERM = "xterm" ]] && stty -parenb -istrip cs8 && bindkey -me 1030 1031 (disable parity detection, don't strip high bit, use 8-bit characters). 1032 Make sure this comes _before_ any bindkey entries in your .zshrc which 1033 redefine keys normally defined in the emacs/vi keymap. You may also 1034 need to set the eightBitOutput resource in your ~/.Xdefaults 1035 file, although this is on by default and it's unlikely anybody will 1036 have tinkered with it. 1037 1038 You don't need the `bindkey' to be able to define your own sequences 1039 with the Meta key, though you still need the `stty'. 1040 1041 If you are using multibyte input directly from the keyboard you 1042 probably don't want to use this feature since the eighth bit in 1043 each byte is used to indicate a part of a multibyte character. See 1044 chapter 5. 1045 10463.6: How do I automatically display the directory in my xterm title bar? 1047 1048 You should use the special function `chpwd', which is called when 1049 the directory changes. The following checks that standard output is 1050 a terminal, then puts the directory in the title bar if the terminal 1051 is an xterm or some close relative, or a sun-cmd. 1052 1053 chpwd() { 1054 [[ -t 1 ]] || return 1055 case $TERM in 1056 sun-cmd) print -Pn "\e]l%~\e\\" 1057 ;; 1058 *xterm*|rxvt|(dt|k|E)term) print -Pn "\e]2;%~\a" 1059 ;; 1060 esac 1061 } 1062 1063 Change `%~' if you want the message to be different. (The `-P' 1064 option interprets such sequences just like in prompts, in this case 1065 producing the current directory; you can of course use `$PWD' here, 1066 but that won't use the `~' notation which I find clearer.) Note that 1067 when the xterm starts up you will probably want to call chpwd 1068 directly: just put `chpwd' in .zshrc after it is defined or autoloaded. 1069 10703.7: How do I make the completion list use eight bit characters? 1071 1072 If you are sure your terminal handles this, the easiest way from versions 1073 3.0.6 and 3.1 of the shell is to set the option PRINT_EIGHT_BIT. In 1074 principle, this will work automatically if your computer uses the 1075 `locale' system and your locale variables are set properly, as zsh 1076 understands this. However, it is quite complicated, so if it isn't 1077 already set up, trying the option is a lot easier. For earlier versions 1078 of zsh 3, you are stuck with trying to understand locales, see the 1079 setlocale(3) and zshparam(1) manual pages: the simplest 1080 possibility may be to set LC_ALL=en_US. For older versions of the 1081 shell, there is no easy way out. 1082 10833.8: Why do the cursor (arrow) keys not work? (And other terminal oddities.) 1084 1085 The cursor keys send different codes depending on the terminal; zsh 1086 only binds the most well known versions. If you see these problems, 1087 try putting the following in your .zshrc: 1088 1089 bindkey "$(echotc kl)" backward-char 1090 bindkey "$(echotc kr)" forward-char 1091 bindkey "$(echotc ku)" up-line-or-history 1092 bindkey "$(echotc kd)" down-line-or-history 1093 1094 If you use vi mode, use `vi-backward-char' and `vi-forward-char' 1095 where appropriate. As of version 4.0.1, zsh attempts to look up these 1096 codes and to set the key bindings for you (both emacs and vi), but in 1097 some circumstances this may not work. 1098 1099 Note, however, that up to version 3.0 binding arbitrary multiple key 1100 sequences can cause problems, so check that this works with your set 1101 up first. Also, from version 3.1.3, more sequences are supported by 1102 default, namely those in the form `<ESC>O' followed by A, 1103 B, C or D, as well as the corresponding set beginning 1104 `<ESC>[', so this may be redundant. 1105 1106 A particular problem which sometimes occurs is that there are two 1107 different modes for arrow keys, normal mode and keypad mode, which 1108 send different sequences. Although this is largely a historical 1109 artifact, it sometimes happens that your terminal can be switched from 1110 one mode to the other, for example by a rogue programme that sends the 1111 sequence to switch one way, but not the sequence to switch back. Thus 1112 you are stuck with the effects. Luckily in this case the arrow key 1113 sequences are likely to be standard, and you can simply bind both sets. 1114 The following code does this. 1115 1116 bindkey '\e[A' up-line-or-history 1117 bindkey '\e[B' down-line-or-history 1118 bindkey '\e[C' forward-char 1119 bindkey '\e[D' backward-char 1120 bindkey '\eOA' up-line-or-history 1121 bindkey '\eOB' down-line-or-history 1122 bindkey '\eOC' forward-char 1123 bindkey '\eOD' backward-char 1124 1125 For most even vaguely VT100-compatible terminals, the above eight 1126 instructions are a fairly safe bet for your .zshrc. Of course 1127 you can substitute variant functions for the second argument here too. 1128 1129 It should be noted that the `O' / `[' confusion can occur 1130 with other keys such as Home and End. Some systems let you query 1131 the key sequences sent by these keys from the system's terminal 1132 database, terminfo. Unfortunately, the key sequences given there 1133 typically apply to the mode that is not the one zsh uses by default (it's 1134 the "application" mode rather than the "raw" mode). Explaining the use 1135 of terminfo is outside the scope of this FAQ, but if you wish to use the 1136 key sequences given there you can tell the line editor to turn on 1137 "application" mode when it starts and turn it off when it stops: 1138 1139 function zle-line-init () { echoti smkx } 1140 function zle-line-finish () { echoti rmkx } 1141 zle -N zle-line-init 1142 zle -N zle-line-finish 1143 1144 If you only have the predecessor to terminfo, called termcap (which is 1145 what we used to get the cursor keys above), replace `echoti smkx' 1146 with `echotc ks' and replace `echoti rmkx' with `echotc ke'. 1147 11483.9: Why does my terminal act funny in some way? 1149 1150 If you are using an OpenWindows cmdtool as your terminal, any 1151 escape sequences (such as those produced by cursor keys) will be 1152 swallowed up and never reach zsh. Either use shelltool or avoid 1153 commands with escape sequences. You can also disable scrolling from 1154 the cmdtool pane menu (which effectively turns it into a shelltool). 1155 If you still want scrolling, try using an xterm with the scrollbar 1156 activated. 1157 1158 If that's not the problem, and you are using stty to change some tty 1159 settings, make sure you haven't asked zsh to freeze the tty settings: 1160 type 1161 1162 ttyctl -u 1163 1164 before any stty commands you use. 1165 1166 On the other hand, if you aren't using stty and have problems you may 1167 need the opposite: `ttyctl -f' freezes the terminal to protect it 1168 from hiccups introduced by other programmes (kermit has been known to 1169 do this). 1170 1171 A problem I have experienced myself (on an AIX 3.2 workstation with 1172 xterm) is that termcap deinitialization sequences sent by `less' 1173 were causing automargins to be turned off --- not actually a shell 1174 problem, but you might have thought it was. The fix is to put `X' 1175 into the environment variable LESS to stop the sequences being sent. 1176 Other programs (though not zsh) may also send that sequence. 1177 1178 If _that_'s not the problem, and you are having difficulties with 1179 external commands (not part of zsh), and you think some terminal 1180 setting is wrong (e.g. ^V is getting interpreted as `literal next 1181 character' when you don't want it to be), try 1182 1183 ttyctl -u 1184 STTY='lnext "^-"' commandname 1185 1186 (in this example). Note that zsh doesn't reset the terminal completely 1187 afterwards: just the modes it uses itself and a number of special 1188 processing characters (see the stty(1) manual page). 1189 11903.10: Why does zsh not work in an Emacs shell mode any more? 1191 1192 (This information comes from Bart Schaefer and other zsh-workers.) 1193 1194 Emacs 19.29 or thereabouts stopped using a terminal type of "emacs" 1195 in shell buffers, and instead sets it to "dumb". Zsh only kicks in 1196 its special I'm-inside-emacs initialization when the terminal type 1197 is "emacs". 1198 1199 Probably the most reliable way of dealing with this is to look for 1200 the environment variable `$EMACS', which is set to `t' in 1201 Emacs' shell mode. Putting 1202 1203 [[ $EMACS = t ]] && unsetopt zle 1204 1205 in your .zshrc should be sufficient. 1206 1207 Another method is to put 1208 1209 #!/bin/sh 1210 TERM=emacs exec zsh 1211 1212 into a file ~/bin/eshell, then `chmod +x ~/bin/eshell', and 1213 tell emacs to use that as the shell by adding 1214 1215 (setenv "ESHELL" (expand-file-name "~/bin/eshell")) 1216 1217 to ~/.emacs. 1218 12193.11: Why do my autoloaded functions not autoload [the first time]? 1220 1221 The problem is that there are two possible ways of autoloading a 1222 function (see the AUTOLOADING FUNCTIONS section of the zsh manual 1223 page zshmisc for more detailed information): 1224 1225 1) The file contains just the body of the function, i.e. 1226 there should be no line at the beginning saying `function foo {' 1227 or `foo () {', and consequently no matching `}' at the end. 1228 This is the traditional zsh method. The advantage is that the 1229 file is called exactly like a script, so can double as both. 1230 To define a function `xhead () { print -n "\033]2;$*\a"; }', 1231 the file would just contain `print -n "\033]2;$*\a"'. 1232 2) The file contains the entire definition, and maybe even 1233 other code: it is run when the function needs to be loaded, then 1234 the function itself is called up. This is the method in ksh. 1235 To define the same function `xhead', the whole of the 1236 usual definition should be in the file. 1237 1238 In old versions of zsh, before 3.0, only the first behaviour was 1239 allowed, so you had to make sure the file found for autoload just 1240 contained the function body. You could still define other functions 1241 in the file with the standard form for definitions, though they 1242 would be redefined each time you called the main function. 1243 1244 In version 3.0.x, the second behaviour is activated if the file 1245 defines the autoloaded function. Unfortunately, this is 1246 incompatible with the old zsh behaviour which allowed you to 1247 redefine the function when you called it. 1248 1249 From version 3.1, there is an option KSH_AUTOLOAD to allow full ksh 1250 compatiblity, i.e. the function _must_ be in the second form 1251 above. If that is not set, zsh tries to guess which form you are 1252 using: if the file contains only a complete definition of the 1253 function in the second form, and nothing else apart from comments 1254 and whitespace, it will use the function defined in the file; 1255 otherwise, it will assume the old behaviour. The option is set 1256 if `emulate ksh' is in effect, of course. 1257 1258 (A neat trick to autoload all functions in a given directory is to 1259 include a line like `autoload ~/fns/*(:t)' in .zshrc; the bit in 1260 parentheses removes the directory part of the filenames, leaving 1261 just the function names.) 1262 12633.12: How does base arithmetic work? 1264 1265 The ksh syntax is now understood, i.e. 1266 1267 let 'foo = 16#ff' 1268 1269 or equivalently 1270 1271 (( foo = 16#ff )) 1272 1273 or even 1274 1275 foo=$((16#ff)) 1276 1277 The original syntax was 1278 1279 (( foo = [16]ff )) 1280 1281 --- this was based on a misunderstanding of the ksh manual page. It 1282 still works but its use is deprecated. Then 1283 1284 echo $foo 1285 1286 gives the answer `255'. It is possible to declare variables explicitly 1287 to be integers, via 1288 1289 typeset -i foo 1290 1291 which has a different effect: namely the base used in the first 1292 assignment (hexadecimal in the example) is subsequently used whenever 1293 `foo' is displayed (although the internal representation is unchanged). 1294 To ensure foo is always displayed in decimal, declare it as 1295 1296 typeset -i 10 foo 1297 1298 which requests base 10 for output. You can change the output base of an 1299 existing variable in this fashion. Using the `$(( ... ))' method will 1300 always display in decimal, except that in 3.1.9 there is a new feature 1301 for selecting a base for displaying here: 1302 1303 print $(( [#16] 255 )) 1304 13053.13: How do I get a newline in my prompt? 1306 1307 You can place a literal newline in quotes, i.e. 1308 1309 PROMPT="Hi Joe, 1310 what now?%# " 1311 1312 If you have the bad taste to set the option cshjunkiequotes, which 1313 inhibits such behaviour, you will have to bracket this with 1314 `unsetopt cshjunkiequotes' and `setopt cshjunkiequotes', or put it 1315 in your .zshrc before the option is set. 1316 1317 In recent versions of zsh (not 3.0), there is a form of quoting which 1318 interprets print sequences like `\n' but otherwise acts like single 1319 quotes: surround the string with $'...'. Hence: 1320 1321 PROMPT=$'Hi Joe,\nwhat now?%# ' 1322 1323 is a neat way of doing what you want. Note that it is the quotes, not 1324 the prompt expansion, which turns the `\n' into a newline. 1325 13263.14: Why does `bindkey ^a command-name' or `stty intr ^-' do something funny? 1327 1328 You probably have the extendedglob option set in which case ^ and # 1329 are metacharacters. ^a matches any file except one called a, so the 1330 line is interpreted as bindkey followed by a list of files. Quote the 1331 ^ with a backslash or put quotation marks around ^a. 1332 See 3.27 if you want to know more about the pattern 1333 character `^'. 1334 13353.15: Why can't I bind \C-s and \C-q any more? 1336 1337 The control-s and control-q keys now do flow control by default, 1338 unless you have turned this off with `stty -ixon' or redefined the 1339 keys which control it with `stty start' or `stty stop'. (This is 1340 done by the system, not zsh; the shell simply respects these 1341 settings.) In other words, \C-s stops all output to the terminal, 1342 while \C-q resumes it. 1343 1344 There is an option NO_FLOW_CONTROL to stop zsh from allowing flow 1345 control and hence restoring the use of the keys: put `setopt 1346 noflowcontrol' in your .zshrc file. 1347 13483.16: How do I execute command `foo' within function `foo'? 1349 1350 The command `command foo' does just that. You don't need this with 1351 aliases, but you do with functions. Note that error messages like 1352 1353 zsh: job table full or recursion limit exceeded 1354 1355 are a good sign that you tried calling `foo' in function `foo' without 1356 using `command'. If `foo' is a builtin rather than an external 1357 command, use `builtin foo' instead. 1358 13593.17: Why do history substitutions with single bangs do something funny? 1360 1361 If you have a command like "echo !-2:$ !$", the first history 1362 substitution then sets a default to which later history substitutions 1363 with single unqualified bangs refer, so that !$ becomes equivalent to 1364 !-2:$. The option CSH_JUNKIE_HISTORY makes all single bangs refer 1365 to the last command. 1366 13673.18: Why does zsh kill off all my background jobs when I logout? 1368 1369 Simple answer: you haven't asked it not to. Zsh (unlike [t]csh) gives 1370 you the option of having background jobs killed or not: the `nohup' 1371 option exists if you don't want them killed. Note that you can always 1372 run programs with `nohup' in front of the pipeline whether or not the 1373 option is set, which will prevent that job from being killed on 1374 logout. (`nohup' is actually an external command.) 1375 1376 The `disown' builtin is very useful in this respect: if zsh informs 1377 you that you have background jobs when you try to logout, you can 1378 `disown' all the ones you don't want killed when you exit. This is 1379 also a good way of making jobs you don't need the shell to know about 1380 (such as commands which create new windows) invisible to the shell. 1381 Likewise, you can start a background job with `&!' instead of just 1382 `&' at the end, which will automatically disown the job. 1383 13843.19: How do I list all my history entries? 1385 1386 Tell zsh to start from entry 1: `history 1'. Those entries at the 1387 start which are no longer in memory will be silently omitted. 1388 13893.20: How does the alternative loop syntax, e.g. `while {...} {...}' work? 1390 1391 Zsh provides an alternative to the traditional sh-like forms with `do', 1392 1393 while TEST; do COMMANDS; done 1394 1395 allowing you to have the COMMANDS delimited with some other command 1396 structure, often `{...}'. The rules are quite complicated and 1397 in most scripts it is probably safer --- and certainly more 1398 compatible --- to stick with the sh-like rules. If you are 1399 wondering, the following is a rough guide. 1400 1401 To make it work you must make sure the TEST itself is clearly 1402 delimited. For example, this works: 1403 1404 while (( i++ < 10 )) { echo i is $i; } 1405 1406 but this does _not_: 1407 1408 while let "i++ < 10"; { echo i is $i; } # Wrong! 1409 1410 The reason is that after `while', any sort of command list is valid. 1411 This includes the whole list `let "i++ < 10"; { echo i $i; }'; 1412 the parser simply doesn't know when to stop. Furthermore, it is 1413 wrong to miss out the semicolon, as this makes the `{...}' part 1414 of the argument to `let'. A newline behaves the same as a 1415 semicolon, so you can't put the brace on the next line as in C. 1416 1417 So when using this syntax, the test following the `while' must 1418 be wrapped up: any of `((...))', `[[...]]', `{...}' or 1419 `(...)' will have this effect. (They have their usual syntactic 1420 meanings too, of course; they are not interchangeable.) Note that 1421 here too it is wrong to put in the semicolon, as then the case 1422 becomes identical to the preceding one: 1423 1424 while (( i++ < 10 )); { echo i is $i; } # Wrong! 1425 1426 The same is true of the `if' and `until' constructs: 1427 1428 if { true } { echo yes } else { echo no } 1429 1430 but with `for', which only needs a list of words, you can get 1431 away with it: 1432 1433 for foo in a b; { echo foo is $a; bar=$foo; } 1434 1435 since the parser knows it only needs everything up to the first 1436 semicolon. For the same reason, there is no problem with the `repeat', 1437 `case' or `select' constructs; in fact, `repeat' doesn't even 1438 need the semicolon since it knows the repeat count is just one word. 1439 1440 This is independent of the behaviour of the SHORTLOOPS option (see 1441 manual), which you are in any case encouraged even more strongly not 1442 to use in programs as it can be very confusing. 1443 14443.21: Why is my history not being saved? 1445 1446 In zsh, you need to set three variables to make sure your history is 1447 written out when the shell exits. For example, 1448 1449 HISTSIZE=200 1450 HISTFILE=~/.zsh_history 1451 SAVEHIST=200 1452 1453 $HISTSIZE tells the shell how many lines to keep internally, 1454 $HISTFILE tells it where to write the history, and $SAVEHIST, 1455 the easiest one to forget, tells it how many to write out. The 1456 simplest possibility is to set it to the same as $HISTSIZE as 1457 above. There are also various options affecting history; see the 1458 manual. 1459 14603.22: How do I get a variable's value to be evaluated as another variable? 1461 1462 The problem is that you have a variable $E containing the string 1463 `EDITOR', and a variable $EDITOR containing the string `emacs', 1464 or something such. How do you get from $E to emacs in one easy 1465 stage? 1466 1467 There is no standard single-stage way of doing this. However, there 1468 is a zsh idiom (available in all versions of zsh since 3.0) for this: 1469 1470 print ${(e)E:+\$$E} 1471 1472 Ignore the `(e)' for now. The `:+' means: if the variable 1473 $E is set, substitute the following, i.e. `\$$E'. This is 1474 expanded to `$EDITOR' by the normal rules. Finally, the `(e)' means 1475 `evaluate the expression you just made'. This gives `emacs'. 1476 1477 For a standard shell way of doing this, you are stuck with `eval': 1478 1479 eval echo \$$E 1480 1481 produces the same result. 1482 1483 Versions since 3.1.6 allow you to do this directly with a new flag; 1484 `${(P)E}'. 1485 1486 As a slight aside, sometimes people note that the syntax `${${E}}' 1487 is valid and expect it to have this effect. It probably ought to, but 1488 in the early days of zsh it was found convenient to have this way of 1489 producing different substitutions on the same parameter; for example, 1490 `${${file##**/}%.*}' removes everything up to the last slash in 1491 `$file', then everything from the last dot on, inclusive (try 1492 it, this works). So in `${${E}}', the internal `${...}' 1493 actually does nothing. 1494 14953.23: How do I prevent the prompt overwriting output when there is no newline? 1496 1497 The problem is normally limited to zsh versions prior to 4.3.0 due to the 1498 advent of the PROMPT_SP option (which is enabled by default, and eliminates 1499 this problem for most terminals). An example of the overwriting is: 1500 1501 % echo -n foo 1502 % 1503 1504 This shows a case where the word foo was output without a newline, and 1505 then overwritten by the prompt line %. The reason this happens is that 1506 the option PROMPT_CR is enabled by default, and it outputs a carriage 1507 return before the prompt in order to ensure that the line editor knows what 1508 column it is in (this is needed to position the right-side prompt correctly 1509 (`$RPROMPT', `$RPS1') and to avoid screen corruption when performing 1510 line editing). If you add unsetopt promptcr to your .zshrc, you 1511 will see any partial output, but your screen may look weird until you press 1512 return or refresh the screen. 1513 1514 A better solution than disabling PROMPT_CR (for most terminals) is adding 1515 a simpler version of the PROMPT_SP functionality to an older zsh using a 1516 custom precmd function, like this one: 1517 1518 # Skip defining precmd if the PROMPT_SP option is available. 1519 if ! eval '[[ -o promptsp ]] 2>/dev/null'; then 1520 function precmd { 1521 # Output an inverse char and a bunch spaces. We include 1522 # a CR at the end so that any user-input that gets echoed 1523 # between this output and the prompt doesn't cause a wrap. 1524 print -nP "%B%S%#%s%b${(l:$((COLUMNS-1)):::):-}\r" 1525 } 1526 fi 1527 1528 That precmd function will only bump the screen down to a new line if there 1529 was output on the prompt line, otherwise the extra chars get removed by 1530 the PROMPT_CR action. Although this typically looks fine, it may result 1531 in the spaces preceding the prompt being included when you select a line 1532 of preserved text with the mouse. 1533 1534 One final alternative is to put a newline in your prompt -- see question 1535 3.13 for that. 1536 15373.24: What's wrong with cut and paste on my xterm? 1538 1539 On the majority of modern UNIX systems, cutting text from one window and 1540 pasting it into another should work fine. On a few, however, there are 1541 problems due to issues about how the terminal is handled: most programs 1542 expect the terminal to be in `canonical input mode', which means that the 1543 program is passed a whole line of input at a time, while for editing 1544 the shell needs a single character at a time and must be in 1545 `non-canonical input mode'. On the systems in question, input can be 1546 lost or re-ordered when the mode changes. There are actually two 1547 slightly different problems: 1548 1549 1) When you paste something in while a programme is running, so that 1550 the shell only retrieves it later. Traditionally, there was a test 1551 which was used only on systems where the problem was known to exist, 1552 so it is possible some other systems were not handled (for example, 1553 certain versions of IRIX, it appears); also, continuation lines were 1554 not handled properly. A more reliable approach appears from versions 1555 3.0.6 and 3.1.6. 1556 2) When the shell is waiting for input, and you paste in a chunk of 1557 text consisting of more than one complete set of commands. 1558 Unfortunately, this is a much harder problem: the line editor is 1559 already active, and needs to be turned off when the first command is 1560 executed. The shell doesn't even know if the remaining text is input 1561 to a command or for the shell, so there's simply nothing it can do. 1562 However, if you have problems you can trick it: type `{' on a line 1563 by itself, then paste the input, then type `}' on a line by 1564 itself. The shell will not execute anything until the final brace is 1565 read; all input is read as continuation lines (this may require the 1566 fixes referred to above in order to be reliable). 1567 15683.25: How do I get coloured prompts on my colour xterm? 1569 1570 (Or `color xterm', if you're reading this in black and white.) 1571 1572 Versions of the shell starting with the 4.3 series have this 1573 built in. Use 1574 1575 PS1='%K{white}%F{red}<red on white>%f%k<default colours>' 1576 1577 to change the prompt. Names are only usable for the colours 1578 black, red, green, yellow, blue, magenta, cyan and white, understood 1579 by most terminals, but if you happen to know the details of how 1580 your terminal implements colours you can specify a number, e.g. 1581 `%20F' to turn the foreground into colour number 20. `echotc 1582 Co' will often output the number of colours the terminal supports. 1583 (Careful: `echotc co' is different; it also outputs a number 1584 but it's the number of columns in the terminal.) If this is 8 1585 then probably you have the named colours and nothing more. 1586 1587 In older versions of the shell you need to find the sequences which 1588 generate the various colours from the manual for your terminal 1589 emulator; these are ANSI standard on those I know about which support 1590 colour. With a recent (post 3.1.6) distribution of zsh, there is a 1591 theme system to handle this for you; even if you don't see that, the 1592 installed function ``colors'' (meaning `colours', if you're not 1593 reading this in black and white) gives the escape sequences. You will 1594 end up with code looking like this (borrowed from Oliver Kiddle): 1595 1596 PS1=$'%{\e[1;31m%}<the rest of your prompt here>%{\e[0m%}' 1597 1598 The `$'' form of quoting turns the ``\e'' into a real escape 1599 character; this only works from about version 3.1.4, so if you're using 1600 3.0.x, you need to do something like 1601 1602 PS1="$(print '%{\e[1;31m%}<the rest goes here>%{\e[0m%}')" 1603 1604 The ``%{...%}'' is used in prompts for strings which will 1605 not appear as characters, so that the prompt code doesn't miscalculate the 1606 length of the prompt which would have a bad effect on editing. The 1607 resulting ``<ESC>[1;31m'' makes the prompt red, and the 1608 ``<ESC>[0m'' puts printing back to normal so that the rest of the line 1609 is unchanged. 1610 16113.26: Why is my output duplicated with `foo 2>&1 >foo.out | bar'? 1612 1613 This is a slightly unexpected effect of the option MULTIOS, which is 1614 set by default. Let's look more closely: 1615 1616 foo 2>&1 >foo.out | bar 1617 1618 What you're probably expecting is that the command `foo' sends its 1619 standard output to the pipe and so to the input of the command `bar', 1620 while it sends its standard error to the file `foo.out'. What you 1621 actually see is that the output is going both to the pipe and into the 1622 file. To be more explicit, here's the same example with real commands: 1623 1624 % { print output; print error >&2 } 2>&1 >foo.out | sed 's/error/erratic' 1625 erratic 1626 output 1627 % cat foo.out 1628 output 1629 1630 and you can see `output' appears twice. 1631 1632 It becomes clearer what's going on if we write: 1633 1634 % print output >foo1.out >foo2.out 1635 % cat foo1.out 1636 output 1637 % cat foo2.out 1638 output 1639 1640 You might recognise this as a standard feature of zsh, called `multios' 1641 and controlled by the option of the same name, whereby output is copied 1642 to both files when the redirector appears twice. What's going on in the 1643 first example is exactly the same, however the second redirector is 1644 disguised as a pipe. So if you want to turn this effect off, you need 1645 to unset the option `MULTIOS'. 1646 16473.27: What are these `^' and `~' pattern characters, anyway? 1648 1649 The characters `^' and `~' are active when the option 1650 EXTENDED_GLOB is set. Both are used to exclude patterns, i.e. to 1651 say `match something other than ...'. There are some confusing 1652 differences, however. Here are the descriptions for `^' and `~'. 1653 1654 `^' means `anything except the pattern that follows'. You can 1655 think of the combination ^pat as being like a * except 1656 that it doesn't match pat. So, for example, `myfile^.txt' 1657 matches anything that begins with myfile except myfile.txt. 1658 Because it works with patterns, not just strings, `myfile^*.c' 1659 matches anything that begins with myfile unless it ends with 1660 .c, whatever comes in the middle --- so it matches myfile1.h 1661 but not myfile1.c. 1662 1663 Also like `*', `^' doesn't match across directories if you're 1664 matching files when `globbing', i.e. when you use an unquoted pattern 1665 in an ordinary command line to generate file names. So 1666 `^dir1/^file1' matches any subdirectory of the current directory 1667 except one called dir1, and within any directory it matches it 1668 picks any file except one called file1. So the overall pattern 1669 matches dir2/file2 but not dir1/file1 nor dir1/file2 nor 1670 dir2/file1. (The rule that all the different bits of the pattern 1671 must match is exactly the same as for any other pattern character, 1672 it's just a little confusing that what does match in each bit is 1673 found by telling the shell not to match something or other.) 1674 1675 As with any other pattern, a `^' expression doesn't treat the 1676 character `/' specially if it's not matching files, for example 1677 when pattern matching in a command like `[[ $string = ^pat1/pat2 ]]'. 1678 Here the whole string pat1/pat2 is treated as the argument that 1679 follows the `^'. So anything matches but that one string 1680 pat1/pat1. 1681 1682 It's not obvious what something like `[[ $string = ^pat1^pat2 ]]' 1683 means. You won't often have cause to use it, but the rule is that 1684 each `^' takes everything that follows as an argument (unless 1685 it's already inside parentheses --- I'll explain this below). To see 1686 this more clearly, put those arguments in parentheses: the pattern is 1687 equivalent to `^(pat1^(pat2))'. where now you can see exactly what 1688 each `^' takes as its argument. I'll leave it as an exercise for 1689 you to work out what this does and doesn't match. 1690 1691 `~' is always used between two patterns --- never right at the 1692 beginning or right at the end. Note that the other special meaning of 1693 `~', at the start of a filename to refer to your home directory or 1694 to another named directory, doesn't require the option 1695 EXTENDED_GLOB to be set. (At the end of an argument `~' is 1696 never special at all. This is useful if you have Emacs backup files.) 1697 It means `match what's in front of the tilde, but only if it doesn't 1698 match what's after the tilde'. So `*.c~f*' matches any file 1699 ending in .c except one that begins with f. You'll see that, 1700 unlike `^', the parts before and after the `~' both refer 1701 separately to the entire test string. 1702 1703 For matching files by globbing, `~' is the only globbing operator 1704 to have a lower precedence than `/'. In other words, when you 1705 have `/a/path/to/match~/a/path/not/to/match' the `~' considers 1706 what's before as a complete path to a file name, and what's after as a 1707 pattern to match against that file. You can put any other pattern 1708 characters in the expressions before and after the `~', but as I 1709 said the pattern after the ~ is really just a single pattern to 1710 match against the name of every file found rather than a pattern to 1711 generate a file. That means, for example, that a * after the 1712 ~ will match a /. If that's confusing, you can think of 1713 how `~' works like this: take the pattern on the left, use it as 1714 normal to make a list of files, then for each file found see if it 1715 matches the pattern on the right and if it does take that file out of 1716 the list. Note, however, that this removal of files happens 1717 immediately, before anything else happens to the file list --- before 1718 any glob qualifiers are applied, for example. 1719 1720 One rule that is common to both `^' and `~' is that they can 1721 be put inside parentheses and the arguments to them don't extend past 1722 the parentheses. So `(^README).txt' matches any file ending in 1723 .txt unless the string before that was README, the same as 1724 `*.txt~README.txt' or `(*~README).txt'. In fact, you can 1725 always turn `^something' into `(*~something)', where 1726 `something' mustn't contain / if the pattern is being used for 1727 globbing. 1728 1729 Likewise, `abc(<->~<10-100>).txt' matches a file consisting of 1730 abc, then some digits, then .txt, unless the digits happen to 1731 match a number from 10 to 100 inclusive (remember the handy `<->' 1732 pattern for matching integers with optional limits to the range). So 1733 this pattern matches abc1.txt or abc200.txt but not 1734 abc20.txt nor abc100.txt nor even abc0030.txt. However, 1735 if you're matching files by globbing note you can't put `/'s 1736 inside the parentheses since the groups can't stretch across multiple 1737 directories. (You can do that, of course, whenever the character 1738 `/' isn't special.) This means that you need to take care when 1739 using exclusions across multiple directories; see some examples below. 1740 1741 You may like to know that from zsh 5.0.3 you can disable any pattern 1742 character separately. So if you find `^' gets in your way and 1743 you're happy using `~', put `disable -p "^"' in ~/.zshrc. 1744 You still need to turn on EXTENDED_GLOB; the disable command 1745 only deactivates things that would otherwise be active, you can't 1746 specially enable something not allowed by the syntax options in effect. 1747 1748 Here are some examples with files to illustrate the points. We'll 1749 assume the option EXTENDED_GLOB is set and none of the pattern 1750 characters is disabled. 1751 1752 1) `**/foo~*bar*' matches any file called `foo' in any 1753 subdirectory, except where `bar' occurred somewhere in the path. 1754 For example, `users/barstaff/foo' will be excluded by the `~' 1755 operator. As the `**' operator cannot be grouped (inside 1756 parentheses it is treated as `*'), this is one way to exclude some 1757 subdirectories from matching a `**'. Note that this can be quite 1758 inefficent because the shell performs a complete search for 1759 `**/foo' before it uses the pattern after the `~' to exclude 1760 files from the match. The file is excluded if `bar' occurs 1761 anywhere, in any directory segment or the final file name. 1762 2) The form `(^foo/)#' can be used to match any hierarchy of 1763 directories where none of the path components is foo. For 1764 example, `(^CVS/)#' selects all subdirectories to any depth 1765 except where one component is named `CVS'. (The form 1766 `(pat/)#' is very useful in other cases; for example, 1767 `(../)#.cvsignore' finds the file .cvsignore if it exists 1768 in the current directory or any parent.) 1769 1770Chapter 4: The mysteries of completion 1771 17724.1: What is completion? 1773 1774 `Completion' is where you hit a particular command key (TAB is the 1775 standard one) and the shell tries to guess the word you are typing 1776 and finish it for you --- a godsend for long file names, in 1777 particular, but in zsh there are many, many more possibilities than 1778 that. 1779 1780 There is also a related process, `expansion', where the shell sees 1781 you have typed something which would be turned by the shell into 1782 something else, such as a variable turning into its value ($PWD 1783 becomes /home/users/mydir) or a history reference (!! becomes 1784 everything on the last command line). In zsh, when you hit TAB it 1785 will look to see if there is an expansion to be done; if there is, 1786 it does that, otherwise it tries to perform completion. (You can 1787 see if the word would be expanded --- not completed --- by TAB by 1788 typing `\C-x g', which lists expansions.) Expansion is generally 1789 fairly intuitive and not under user control; for the rest of the 1790 chapter I will discuss completion only. 1791 1792 An elegant completion system appeared in version 4, replacing the old 1793 compctl command. This is based on functions called automatically for 1794 completion in particular contexts (for example, there is a function 1795 called _cd to handle completion for the cd command) and is 1796 installed automatically with the shell, so all you need to do, in 1797 principal, is to arrange for this to be loaded. Putting `autoload -U 1798 compinit; compinit' in your .zshrc should be enough if the system is 1799 installed properly. 1800 18014.2: What sorts of things can be completed? 1802 1803 The simplest sort is filename completion, mentioned above. Unless 1804 you have made special arrangements, as described below, then after 1805 you type a command name, anything else you type is assumed by the 1806 completion system to be a filename. If you type part of a word and 1807 hit TAB, zsh will see if it matches the first part a filename and 1808 if it does it will automatically insert the rest. 1809 1810 The other simple type is command completion, which applies 1811 (naturally) to the first word on the line. In this case, zsh 1812 assumes the word is some command to be executed lying in your $PATH 1813 (or something else you can execute, like a builtin command, a 1814 function or an alias) and tries to complete that. 1815 1816 However, the new completion system is highly sensitive to context 1817 and comes with completions for many UNIX commands. These are 1818 automatically loaded when you run compinit as described above. 1819 So the real answer to the question `what can be completed?' is 1820 `anything where an automated guess is possible'. Just hit TAB 1821 and see if the shell manages to guess correctly. 1822 18234.3: How does zsh deal with ambiguous completions? 1824 1825 Often there will be more than one possible completion: two files 1826 start with the same characters, for example. Zsh has a lot of 1827 flexibility for what it does here via its options. The default is 1828 for it to beep and completion to stop until you type another 1829 character. You can type \C-D to see all the possible completions. 1830 (That's assuming you're at the end of the line, otherwise \C-D will 1831 delete the next character and you have to use ESC-\C-D.) This can be 1832 changed by the following options, among others: 1833 1834 o with NO_BEEP set, that annoying beep goes away 1835 o with NO_LIST_BEEP, beeping is only turned off for ambiguous 1836 completions 1837 o with AUTO_LIST set, when the completion is ambiguous you get a 1838 list without having to type \C-D 1839 o with BASH_AUTO_LIST set, the list only happens the second 1840 time you hit tab on an ambiguous completion 1841 o with LIST_AMBIGUOUS, this is modified so that nothing is listed if 1842 there is an unambiguous prefix or suffix to be inserted --- this 1843 can be combined with BASH_AUTO_LIST, so that where both are 1844 applicable you need to hit tab three times for a listing. 1845 o with MENU_COMPLETE set, one completion is always inserted 1846 completely, then when you hit TAB it changes to the next, and so 1847 on until you get back to where you started 1848 o with AUTO_MENU, you only get the menu behaviour when you hit TAB 1849 again on the ambiguous completion. 1850 o Finally, although it affects all completion lists, including 1851 those explicitly requested, note also ALWAYS_LAST_PROMPT, which 1852 causes the cursor to return to the line you were editing after 1853 printing the list, provided that is short enough. 1854 1855 Combinations of these are possible; for example, AUTO_LIST and 1856 AUTO_MENU together give an intuitive combination. Note that 1857 from version 3.1 LIST_AMBIGUOUS is set by default; if you use 1858 autolist, you may well want to `unsetopt listambiguous'. 1859 18604.4: How do I complete in the middle of words / just what's before the cursor? 1861 1862 Sometimes you have a word on the command-line which is incomplete in the 1863 middle. Normally if you hit tab in zsh, it will simply go to the end of 1864 the word and try to complete there. However, there are two ways of 1865 changing this. 1866 1867 First, there is the option COMPLETE_IN_WORD. This tries to fill in 1868 the word at the point of the cursor. For example, if the current 1869 directory contains `foobar', then with the option set, you can 1870 complete `fbar' to `foobar' by moving the cursor to the 1871 `b' and hitting tab. 1872 1873 To complete just what's before the cursor, ignoring anything after, you 1874 need the function expand-or-complete-prefix: it works mostly like the 1875 usual function bound to tab, but it ignores anything on the right of the 1876 cursor. If you always want this behaviour (some other shells do this), 1877 bind it to tab; otherwise put another binding, e.g. `^X TAB' in 1878 ~/.zshrc: 1879 1880 bindkey "^X^I" expand-or-complete-prefix 1881 1882 The completion system's handling of filenames allows you to complete 1883 multiple segments of a path in one go, so for example /u/l/b 1884 can expand to /usr/local/bin or anything else that matches. This 1885 saves you having to expand the middle part of the path separately. 1886 18874.5: How do I get started with programmable completion? 1888 1889 The main resource is the zshcompsys manual page. It's complicated, 1890 I'm afraid, far too much to go into here. See also the user guide 1891 referred to above, or copy one of the very many existing functions. For 1892 a professionally produced guide, see the book `From Bash to Z Shell: 1893 Conquering the Command Line' by Oliver Kiddle, Jerry Peek and Peter 1894 Stephenson (me), published by Apress, ISBN 1-59059-376-6. Chapter 10 1895 tells you how to configure the completion system and chapter 15 how 1896 to write your own completion functions. 1897 18984.6: Suppose I want to complete all files during a special completion? 1899 1900 If you're using the completion system the shell will decide what 1901 to complete when you hit TAB. That's usually the right thing for 1902 the context, but sometimes you just want to complete files, like 1903 TAB used to do in the old days. You can set up this up as follows: 1904 1905 zle -C complete-file complete-word _generic 1906 zstyle ':completion:complete-file::::' completer _files 1907 bindkey '^xF' complete-file 1908 1909 This turns the key \C-x F into a command complete-file which 1910 goes straight to the completion system's file completion command, 1911 ignoring the normal context. Change the binding how you like. 1912 1913 Note the way the form of completion to use is specified by picking a 1914 `completer' called `_files'. You can define any completion 1915 to be bound to a keystroke by putting the appropriate completion 1916 function at that point. Then change all occurrences of 1917 `complete-file' to a name of your own. 1918 1919 If you simply want to try filename completion as a default when other 1920 completions fail, add it to the `completer' style for normal 1921 completion, for example: 1922 1923 zstyle ':completion:*' completer _complete _ignored _files 1924 1925 This adds filename completion to the end of the default types of 1926 completion. Your actual completer style may include other actions, 1927 such as expansion or approximate completion. 1928 1929Chapter 5: Multibyte input and output 1930 19315.1: What is multibyte input? 1932 1933 For a long time computers had a simple idea of a character: each octet 1934 (8-bit byte) of text contained one character. This meant an application 1935 could only use 256 characters at once. The first 128 characters (0 to 1936 127) on Unix and similar systems usually corresponded to the ASCII 1937 character set, as they still do. So all other possibilities had to be 1938 crammed into the remaining 128. This was done by picking the appropriate 1939 character set for the use you were making. For example, ISO 8859 1940 specified a set of extensions to ASCII for various alphabets. 1941 1942 This was fine for simple extensions and certain short enough relatives of 1943 the Latin alphabet (with no more than a few dozen alphabetic characters), 1944 but useless for complex alphabets. Also, having a different character 1945 set for each language is inconvenient: you have to start a new terminal 1946 to run the shell with each character set. So the character set had to be 1947 extended. To cut a long story short, the world has mostly standardised 1948 on a character set called Unicode, related to the international standard 1949 ISO 10646. The intention is that this will contain every single 1950 character used in all the languages of the world. 1951 1952 This has far too many characters to fit into a single octet. What's 1953 more, UNIX utilities such as zsh are so used to dealing with ASCII that 1954 removing it would cause no end of trouble. So what happens is this: the 1955 128 ASCII characters are kept exactly the same (and they're the same as 1956 the first 128 characters of Unicode), but the remaining 128 characters 1957 are used to build up any other Unicode character by combining multiple 1958 octets together. The shell doesn't need to interpret these directly; it 1959 just needs to ask the system library how many octets form the next 1960 character, and if there's a valid character there at all. (It can also 1961 ask the system what width the character takes up on the screen, so that 1962 characters no longer need to be exactly one position wide.) 1963 1964 The way this is done is called UTF-8. Multibyte encodings of other 1965 character sets exist (you might encounter them for Asian character sets); 1966 zsh will be able to use any such encoding as long as it contains ASCII as 1967 a single-octet subset and the system can provide information about other 1968 characters. However, in the case of Unicode, UTF-8 is the only one you 1969 are likely to enounter that is useful in zsh. 1970 1971 (In case you're confused: Unicode is the character set, while UTF-8 is 1972 an encoding of it. You might hear about other encodings, such as UCS-2 1973 and UCS-4 which are basically the character's index in the character set 1974 as a two-octet or four-octet integer. You might see files encoded this 1975 way, for example on Windows, but the shell can't deal directly with text 1976 in those formats.) 1977 19785.2: How does zsh handle multibyte input and output? 1979 1980 Until version 4.3, zsh didn't handle multibyte input properly at all. 1981 Each octet in a multibyte character would look to the shell like a 1982 separate character. If your terminal handled the character set, 1983 characters might appear correct on screen, but trying to edit them would 1984 cause all sorts of odd effects. (It was possible to edit in zsh using 1985 single-byte extensions of ASCII such as the ISO 8859 family, however.) 1986 1987 From version 4.3.4, multibyte input is handled in the line editor if zsh 1988 has been compiled with the appropriate definitions, and is automatically 1989 activated. This is indicated by the option MULTIBYTE, which is 1990 set by default on shells that support multibyte mode. Hence you 1991 can test this with a standard option test: `[[ -o multibyte ]]'. 1992 1993 The MULTIBYTE option affects the entire shell: parameter expansion, 1994 pattern matching, etc. count valid multibyte character strings as a 1995 single character. You can unset the option locally in a function to 1996 revert to single-byte operation. 1997 1998 Note that if the shell is emulating a Bourne shell the MULTIBYTE 1999 option is unset by default. This allows various POSIX modes to 2000 work normally (POSIX does not deal with multibyte characters). If 2001 you use a "sh" or "ksh" emulation interactively you should probably 2002 set the MULTIBYTE option. 2003 2004 The other option that affects multibyte support is COMBINING_CHARS, 2005 new in version 4.3.9. When this is set, any zero-length punctuation 2006 characters that follow an alphanumeric character (the base character) are 2007 assumed to be modifications (accents etc.) to the base character and to 2008 be displayed within the same screen area as the base character. As not 2009 all terminals handle this, even if they correctly display the base 2010 multibyte character, this option is not on by default. Recent versions 2011 of the KDE and GNOME terminal emulators konsole and 2012 gnome-terminal as well as rxvt-unicode, and the Unicode version 2013 of xterm, xterm -u8 or the front-end uxterm, are known to handle 2014 combining characters. 2015 2016 The COMBINING_CHARS option only affects output; combining characters 2017 may always be input, but when the option is off will be displayed 2018 specially. By default this is as a code point (the index of the 2019 character in the character set) between angle brackets, usually 2020 in inverse video. Highlighting of such special characters can 2021 be modified using the new array parameter zle_highlight. 2022 20235.3: How do I ensure multibyte input and output work on my system? 2024 2025 Once you have a version of zsh with multibyte support, you need to 2026 ensure the environment is correct. We'll assume you're using UTF-8. 2027 Many modern systems may come set up correctly already. Try one of 2028 the editing widgets described in the next section to see. 2029 2030 There are basically three components. 2031 2032 o The locale. This describes a whole series of features specific 2033 to countries or regions of which the character set is one. Usually 2034 it is controlled by the environment variable LANG (there are 2035 others but this is the one to start with). You need to find a 2036 locale whose name contains `UTF-8'. This will be a variant on 2037 your usual locale, which typically indicates the language and 2038 country; for example, mine is `en_GB.UTF-8'. Luckily, zsh can 2039 complete locale names, so if you have the new completion system 2040 loaded you can type `export LANG=' and attempt to complete a 2041 suitable locale. It's the locale that tells the shell to expect the 2042 right form of multibyte input. (However, there's no guarantee that 2043 the shell is actually going to get this input: for example, if you 2044 edit file names that have been created using a different character 2045 set it won't work properly.) 2046 o The terminal emulator. Those that are supplied with a recent 2047 desktop environment, such as konsole and gnome-terminal, are 2048 likely to have extensive support for localization and may work 2049 correctly as soon as they know the locale. You can enable UTF-8 2050 support for xterm in its application defaults file. The 2051 following are the relevant resources; you don't actually need all of 2052 them, as described below. If you use a `~/.Xdefaults' or 2053 `~/.Xresources' file for setting resources, prefix all the lines 2054 with `xterm': 2055 2056 *wideChars: true 2057 *locale: true 2058 *utf8: 1 2059 *vt100Graphics: true 2060 2061 This turns on support for wide characters (this is enabled by the 2062 utf8 resource, too); enables conversions to UTF-8 from other 2063 locales (this is the key resource and actually overrides 2064 `utf8'); turns on UTF-8 mode (this resource is mostly used to 2065 force use of UTF-8 characters if your locale system isn't up to it); 2066 and allows certain graphic characters to work even with UTF-8 2067 enabled. (Thanks to Phil Pennock for suggestions.) 2068 o The font. If you selected this from a menu in your terminal 2069 emulator, there's a good chance it already selected the right 2070 character set to go with it. If you hand-picked an old fashioned 2071 X font with a lot of dashes, you need to make sure it ends with 2072 the right character encoding, `iso10646-1' (and not, for 2073 example, `iso8859-1'). Not all characters will be available 2074 in any font, and some fonts may have a more restricted range of 2075 Unicode characters than others. 2076 2077 As mentioned in the previous section, `bindkey -m' now outputs 2078 a warning message telling you that multibyte input from the terminal 2079 is likely not to work. (See 3.5 if you don't know what 2080 this feature does.) If your terminal doesn't have characters 2081 that need to be input as multibyte, however, you can still use 2082 the meta bindings and can ignore the warning message. Use 2083 `bindkey -m 2>/dev/null' to suppress it. 2084 2085 You might also note that the latest version of the Cygwin environment 2086 for Windows supports UTF-8. In previous versions, zsh was able 2087 to compile with the MULTIBYTE option enabled, but the system 2088 didn't provide full support for it. 2089 20905.4: How can I input characters that aren't on my keyboard? 2091 2092 Two functions are provided with zsh that help you input characters. 2093 As with all editing widgets implemented by functions, you need to 2094 mark the function for autoload, create the widget, and, if you are 2095 going to use it frequently, bind it to a key sequence. The 2096 following binds insert-composed-char to F5 on my keyboard: 2097 2098 autoload -Uz insert-composed-char 2099 zle -N insert-composed-char 2100 bindkey '\e[15~' insert-composed-char 2101 2102 The two widgets are described in the zshcontrib(1) manual 2103 page, but here is a brief summary: 2104 2105 insert-composed-char is followed by two characters that 2106 are a mnemonic for a multibyte character. For example `a:' 2107 is a with an Umlaut; `cH' is the symbol for hearts on a playing 2108 card. Various accented characters, European and related alphabets, 2109 and punctuation and mathematical symbols are available. The 2110 mnemonics are mostly those given by RFC 1345, see 2111 http://www.faqs.org/rfcs/rfc1345.html. 2112 2113 insert-unicode-char is used to input a Unicode character by 2114 its hexadecimal number. This is the number given in the Unicode 2115 character charts, see for example http://www.unicode.org/charts/. 2116 You need to execute the function, then type the hexadecimal number 2117 (you can omit any leading zeroes), then execute the function again. 2118 2119 Both functions can be used without multibyte mode, provided the locale is 2120 correct and the character selected exists in the current character set; 2121 however, using UTF-8 massively extends the number of valid characters 2122 that can be produced. 2123 2124 If you have a recent X Window System installation, you might find 2125 the AltGr key helps you input accented Latin characters; for 2126 example on my keyboard AltGr-; e gives `e' with an acute accent. 2127 See also http://www.cl.cam.ac.uk/~mgk25/unicode.html#input 2128 for general information on entering Unicode characters from a keyboard. 2129 2130Chapter 6: The future of zsh 2131 21326.1: What bugs are currently known and unfixed? (Plus recent important changes) 2133 2134 Bugs tend to be tracked on the zsh-workers mailing list; see the 2135 next section. Check the mailing list to see if a bug has been 2136 reported. (There is a bug tracker at the zsh development site 2137 at Sourceforge, but it's not in active use.) 2138 2139 To see how recent versions of the shell have changed, look at 2140 the README file in the source distribution. This indicates the 2141 most important changes, and in particular draws attention to 2142 incompatibilities you might notice. 2143 21446.2: Where do I report bugs, get more info / who's working on zsh? 2145 2146 The shell is being maintained by various (entirely self-appointed) 2147 subscribers to the mailing list, 2148 2149 zsh-workers@zsh.org 2150 2151 so mail on any issues (bug reports, suggestions, complaints...) 2152 related to the development of the shell should be sent there. If 2153 you want someone to mail you directly, say so. Most patches to zsh 2154 appear there first. 2155 2156 Note that this location has just changed (January 1999), and the 2157 instructions to go with it are slightly different --- in particular, 2158 if you are already subscribed, the instructions about how to 2159 unsubscribe are different. 2160 2161 Please note when reporting bugs that many exist only on certain 2162 architectures, which the developers may not have access to. In 2163 this case debugging information, as detailed as possible, is 2164 particularly welcome. 2165 2166 Two progressively lower volume lists exist, one with messages 2167 concerning the use of zsh, 2168 2169 zsh-users@zsh.org 2170 2171 and one just containing announcements: about releases, about major 2172 changes in the shell, or this FAQ, for example, 2173 2174 zsh-announce@zsh.org 2175 2176 (posting to the last one is currently restricted). 2177 2178 Note that you should only join one of these lists: people on 2179 zsh-workers receive all the lists, and people on zsh-users will 2180 also receive the announcements list. 2181 2182 The lists are handled by an automated server. The instructions for 2183 zsh-announce and zsh-users are the same as for zsh-workers: just 2184 change zsh-workers to whatever in the following. 2185 2186 To join zsh-workers, send email to 2187 2188 zsh-workers-subscribe@zsh.org 2189 2190 (the actual content is unimportant). Replace subscribe with 2191 unsubscribe to unsubscribe. The mailing software (ezlm) has 2192 various bells and whistles: you can retrieve archived messages. 2193 Mail zsh-workers-help@zsh.org for detailed information. 2194 Adminstrative matters are best sent to 2195 zsh-workers-owner@zsh.org. 2196 real name is Geoff Wing <gcw@zsh.org>. 2197 2198 An archive of mailings for the last few years can be found at 2199 http://www.zsh.org/mla/ 2200 at the main zsh archive in Australia. 2201 2202 Of course, you can also post zsh queries to the Usenet group 2203 comp.unix.shell; if all else fails, you could even e-mail me. 2204 22056.3: What's on the wish-list? 2206 2207 The code bears the marks of the ages and many things could be done much 2208 better with a rewrite. A more efficient set of code for 2209 lexing/parsing/execution might also be an advantage. Volunteers are 2210 particularly welcome for these tasks. 2211 2212 Some future possibilities which have been suggested: 2213 2214 o The shell, in particular the line editor, should support Unicode 2215 characters. Initial support for this appeared in version 4.3; 2216 it is reasonably complete in the line editor but patchy elsewhere 2217 (note this may require the configuration option --enable-multibyte). 2218 o The parameter code could do with tidying up, maybe with more of the 2219 features made available in ksh93. 2220 o Configuration files to enable zsh startup files to be created 2221 with the Dotfile Generator. 2222 o Further improvements in integrating the line editor with shell 2223 functions. 2224 o POSIX compatibility could be improved. 2225 o Option for glob qualifiers to follow perl syntax (a traditional item). 2226 22276.4: Did zsh have problems in the year 2000? 2228 2229 Not that I heard of; it's up to you to be careful with two-digit dates, 2230 though, which are produced by the prompt escapes `%W' and `%D', 2231 and also by the command `print -P'. Earlier versions of zsh may 2232 show problems here. 2233 2234Acknowledgments: 2235 2236Thanks to zsh-list, in particular Bart Schaefer, for suggestions 2237regarding this document. Zsh has been in the hands of archivists Jim 2238Mattson, Bas de Bakker, Richard Coleman, Zoltan Hidvegi and Andrew 2239Main, and the mailing list has been run by Peter Gray, Rick Ohnemus, 2240Richard Coleman, Karsten Thygesen and Geoff Wing, all of whom deserve 2241thanks. The world is eternally in the debt of Paul Falstad for inventing 2242zsh in the first place (though the wizzo extended completion is by Sven 2243Wischnowsky). 2244 2245Copyright Information: 2246 2247This document is copyright (C) P.W. Stephenson, 1995, 1996, 1997, 22481998, 1999, 2000, 2012. This text originates in the U.K. and the author 2249asserts his moral rights under the Copyrights, Designs and Patents Act, 22501988. 2251 2252Permission is hereby granted, without written agreement and without 2253license or royalty fees, to use, copy, modify, and distribute this 2254documentation for any purpose, provided that the above copyright 2255notice appears in all copies of this documentation. Remember, 2256however, that this document changes monthly and it may be more useful 2257to provide a pointer to it rather than the entire text. A suitable 2258pointer is "information on the Z-shell can be obtained on the World 2259Wide Web at URL http://zsh.sourceforge.net/". 2260