1----------------- 2THE Z SHELL (ZSH) 3----------------- 4 5Version 6------- 7 8This is version 5.0.2 of the shell. This is a stable release. 9There are minor new features as well as bug fixes since 5.0.0 and 10one bug fix since the short-lived 5.0.1. 11 12Installing Zsh 13-------------- 14 15The instructions for compiling zsh are in the file INSTALL. You should 16also check the file MACHINES in the top directory to see if there 17are any special instructions for your particular architecture. 18 19Note in particular the zsh/newuser module that guides new users through 20setting basic shell options without the administrator's intervention. This 21is turned on by default. See the section AUTOMATIC NEW USER CONFIGURATION 22in INSTALL for configuration information. 23 24Features 25-------- 26 27Zsh is a shell with lots of features. For a list of some of these, see the 28file FEATURES, and for the latest changes see NEWS. For more 29details, see the documentation. 30 31Incompatibilities between 5.0.0 and 5.0.2 32----------------------------------------- 33 34In 5.0.0, the new "sticky" emulation feature was applied to functions 35explicitly declared within an expression following `emulate ... -c', but 36did not apply to functions marked for autoload in that expression. This 37was not documented and experience suggests it was inconvenient, so in 385.0.2 autoloads also have the sticky property. 39 40In other words, 41 42 emulate zsh -c 'func() { ... }' 43 44behaves the same way in 5.0.0 and 5.0.2, with the function func always being 45run in native zsh emulation regardless of the current option settings. 46However, 47 48 emulate zsh -c 'autoload -Uz func' 49 50behaves differently: in 5.0.0, func was loaded with the options in 51effect at the point where it was first run, and subsequently run with 52whatever options were in effect at that point; in 5.0.2, func is loaded 53with native zsh emulation options and run with those same options. This 54is now the recommended way of ensuring a function is loaded and run with 55a consistent set of options. 56 57Note that the command `autoload -z' has never affected the options 58applied when the function is loaded or run, only the effect of the 59KSH_AUTOLOAD option at the point the function is loaded. 60 61Possible incompatibilities between 4.2 and 5.0 62---------------------------------------------- 63 64Here are some incompatibilities in the shell since the 4.2 series of 65releases. It is hoped most users will not be adversely affected by these. 66 67In previous releases of the shell, builtin commands and precommand 68modifiers that did not accept options also did not recognize the 69argument "--" as marking the end of option processing without being 70considered an argument. This was not documented and was incompatible 71with other shells. All such commands now handle this syntax. 72 73The configuration option --enable-lfs to enable large file support has 74been replaced by autoconf's standard --enable-largefile mechanism. 75As this is usually used whenever necessary, this won't usually 76be noticeable; however, anyone configuring with --disable-lfs 77should configure with --disable-largefile instead. 78 79The configuration option --with-curses-terminfo has been replaced 80by the option --with-term-lib="LIBS" where LIBS is a space-separated 81list of libraries to search for termcap and curses features. 82 83The option SH_WORD_SPLIT, used in Bourne/Korn/Posix shell compatibility 84mode, has been made more like other shells in the case of substitutions of 85the form ${1+"$@"} (a common trick used to work around problems in older 86Bourne shells) or any of the related forms with the + replaced by - or = 87with an optional colon preceding. Previously, with SH_WORD_SPLIT in 88effect, this expression would cause splitting on all white space in the 89shell arguments. (This was always regarded as a bug but was long-standing 90behaviour.) Now it is treated identically to "$@". The same change 91applies to expressions with forced splitting such as ${=1+"$@"}, but 92otherwise the case where SH_WORD_SPLIT is not set is unaffected. 93 94Debug traps (`trap ... DEBUG' or the function TRAPDEBUG) now run by default 95before the command to which they refer instead of after. This is almost 96always the right behaviour for the intended purpose of debugging and is 97consistent with recent versions of other shells. The option 98DEBUG_BEFORE_CMD can be unset to revert to the previous behaviour. 99 100Previously, process substitutions of the form =(...), <(...) and >(...) 101were only handled if they appeared as separate command arguments. 102(However, the latter two forms caused the current argument to be 103terminated and a new one started even if they occurred in the middle of 104a string.) Now all three may be followed by other strings, and the 105latter two may also be preceded by other strings. Remaining 106limitations on their use (to reduce incompatibilities to a minimum) 107are documented in the zshexpn.1 manual. 108 109In previous versions of the shell it was possible to use index 0 in an 110array or string subscript to refer to the same element as index 1 if the 111option KSH_ARRAYS was not in effect. This was a limited approximation to 112the full KSH_ARRAYS handling and so was not very useful. In this version 113of the shell, this behaviour is only provided when the option 114KSH_ZERO_SUBSCRIPT is set. Note that despite the name this does not provide 115true compatibility with ksh or other shells and KSH_ARRAYS should still be 116used for that purpose. By default, the option is not set; an array 117subscript that evaluates to 0 returns an empty string or array element and 118attempts to write to an array or string range including only a zero 119subscript are treated as an error. Writes to otherwise valid ranges that 120also include index zero are allowed; hence for example the assignment 121 array[(R)notfound,(r)notfound]=() 122(where the string "notfound" does not match an element in $array) sets the 123entire array to be empty, as in previous versions of the shell. 124KSH_ZERO_SUBSCRIPT is irrelevant when KSH_ARRAYS is set. Also as in previous 125versions, attempts to write to non-existent elements at the end of an array 126cause the array to be suitably extended. This difference means that, for 127example 128 array[(R)notfound]=(replacement) 129is an error if KSH_ZERO_SUBSCRIPT is not set (new behaviour), while 130 array[(r)notfound]=(replacement) 131causes the given value to be appended to the array (same behaviour as 132previous versions). 133 134The "exec" precommand modifier now takes various options for compatibility 135with other shells. This means that whereas "exec -prog" previously 136tried to execute a command name "-prog", it will now report an error 137in option handling. "exec -- -prog" will execute "-prog". If 138the option EQUALS is set, as it is by default in zsh's native mode, 139"exec =-prog" behaves the same way in all versions of zsh provided 140the command can be found. 141 142The "unset" builtin now does not regard the unsetting of non-existent 143variables as an error, so can still return status 0 (depending on the 144handling of other arguments). This appears to be the standard shell 145behaviour. 146 147The variable BAUD is no longer set automatically by the shell. 148In previous versions it was set to the baud rate reported by 149the terminal driver in order to initialise the line editor's 150compensation mechanism for slow baud rates. However, the baud 151rate so reported is very rarely related to the limiting speed of 152screen updates on modern systems. Users who need the compensation 153mechanism should set BAUD to an appropriate rate by hand. 154 155The variable HOME is no longer set by the shell if zsh is emulating any 156other shell at startup; it must be present in the environment or set 157subsequently by the user. It is valid for the variable to be unset. 158 159If the shell starts in a mode where it is emulating another shell 160(typically because the base name of the shell was "sh" or another known 161shell), the "repeat" syntax is not available by default, to avoid clashes 162with external commands, but the "ulimit" command is available by default. 163"limit", "sched" and "unlimit" are not available by default in such modes: 164this has been the case for many versions but is now documented for the 165first time. (Users should note that emulation modes are not designed for 166backwards compatibility with previous versions of zsh, but to maximise 167compatibility with other shells, hence it is not safe to assume emulation 168modes will behave consistently between zsh versions.) 169 170Parameter substitutions in the form ${param//#%search/replace} match 171against "search" anchored at both ends of the parameter value. Previously 172this syntax would have matched against "%search", anchored only at the head 173of the value. The form ${param//#$search/replace} where the value 174$search starts with "%" considers the "%" to be part of the search 175string as before. 176 177Configure attempts to decide if multibyte characters are supported by the 178system and if so sets the effect of --enable-multibyte, unless 179--disable-multibyte was passed on the command line. When 180--enable-multibyte is in effect, the MULTIBYTE shell option is on by 181default; this causes many operations to recognise characters in the current 182locale. (Most typically this is used for a UTF-8 character set but the 183shell will work with any character set provided by the system where 184individual octets are either US ASCII characters or have the top bit set.) 185Older versions of the shell always assumed a character was one byte; this 186remains the case if --disable-multibyte is in effect or if the MULTIBYTE 187option is unset. In some places the width of characters will be taken into 188account where previously a raw string length was used; this is transparent 189in calculations of screen position, but also occurs, for example, in 190calculations of padding width. Note that MULTIBYTE is not automatically 191set when emulating Bourne- and POSIX-style shells; for interactive use of 192these emulations it may be necessary to set it by hand. Note also that the 193option COMBINING_CHARS is not set by default due to difficulties detecting 194the ability of the terminal to display combining characters correctly; MAC 195users in particular will probably wish to set this option. 196 197Zsh has previously been lax about whether it allows octets with the 198top bit set to be part of a shell identifier. Older versions of the shell 199assumed all such octets were allowed in identifiers, however the POSIX 200standard does not allow such characters in identifiers. The older 201behaviour is still obtained with --disable-multibyte in effect. 202With --enable-multibyte in effect (see previous paragraph) there are three 203possible cases: 204 MULTIBYTE option unset: only ASCII characters are allowed; the 205 shell does not attempt to identify non-ASCII characters at all. 206 MULTIBYTE option set, POSIX_IDENTIFIERS option unset: in addition 207 to the POSIX characters, any alphanumeric characters in the 208 local character set are allowed. Note that scripts and functions that 209 take advantage of this are non-portable; however, this is in the spirit 210 of previous versions of the shell. Note also that the options must 211 be set before the shell parses the script or function; setting 212 them during execution is not sufficient. 213 MULITBYTE option set, POSIX_IDENTIFIERS set: only ASCII characters 214 are allowed in identifiers even though the shell will recognise 215 alphanumeric multibyte characters. 216 217The sched builtin now keeps entries in time order. This means that 218after adding an entry the index of an existing entry used for deletion 219may change, if that entry had a later time than the new entry. However, 220deleting a entry with a later time will now never change the index of an 221entry with an earlier time, which could happen with the previous method. 222 223The completion style pine-directory must now be set to use completion 224for PINE mailbox folders; previously it had the default ~/mail. This 225change was necessary because otherwise recursive directories under 226~/mail were searched by default, which could be a considerable unnecessary 227hit for anyone not using PINE. The previous default can be restored with: 228 zstyle ':completion:*' pine-directory ~/mail 229 230The completion style fake-files now allows patterns as directories, 231for example the value '/home/*:.snapshot' is now valid. This will 232only cause problems in the unlikely event that a directory in the style 233has a pattern character in it. 234 235The default maximum function depth (configurable with 236--enable-max-function-depth) has been decreased to 1000 from 4096. The 237previous value was observed to be small enough that crashes still occurred 238on some fairly common PC configurations. This change is only likely to 239affect some highly specialised uses of the shell. 240 241The variables HISTCHARS and histchars now reject any attempt to 242set non-ASCII characters for history or comments. Multibyte characters 243have never worked and the most consistent change was to restrict the 244set to portable characters only. 245 246Writers of add-on modules should note that the API has changed 247significantly to allow user control of individual features provided by 248modules. See the documentation for zmodload -F and 249Etc/zsh-development-guide, in that order. 250 251Documentation 252------------- 253 254There are a number of documents about zsh in this distribution: 255 256Doc/Zsh/*.yo The master source for the zsh documentation is written in 257 yodl. Yodl is a document language written by Karel Kubat. 258 It is not required by zsh but it is a nice program so you 259 might want to get it anyway, especially if you are a zsh 260 developer. It can be downloaded from 261 ftp://yodl.sourceforge.net/ 262 263Doc/zsh*.1 Man pages in nroff format. These will be installed 264 by "make install.man" or "make install". By default, 265 these will be installed in /usr/local/man/man1, although 266 you can change this with the --mandir option to configure 267 or editing the user configuration section of the top level 268 Makefile. 269 270Doc/zsh.texi Everything the man pages have, but in texinfo format. These 271 will be installed by "make install.info" or "make install". 272 By default, these will be installed in /usr/local/info, 273 although you can change this with the --infodir option to 274 configure or editing the user configuration section of the 275 top level Makefile. Version 4.0 or above of the 276 Texinfo tools are recommended for processing this file. 277 278Also included in the distribution are: 279 280Doc/intro.ms An introduction to zsh in troff format using the ms 281 macros. This document explains many of the features 282 that make zsh more equal than other shells. 283 Unfortunately this is based on zsh-2.5 so some examples 284 may not work without changes but it is still a good 285 introduction. 286 287For more information, see the website, as described in the META-FAQ. 288 289If you do not have the necessary tools to process these documents, PDF, 290Info and DVI versions are available in the separate file zsh-doc.tar.gz at 291the archive sites listed in the META-FAQ. 292 293The distribution also contains a Perl script in Utils/helpfiles which 294can be used to extract the descriptions of builtin commands from the 295zshbuiltins manual page. See the comments at the beginning of the 296script about its usage. The files created by this script can be used 297by example function run-help located in the subdirectory Functions/Misc to 298show information about zsh builtins and run `man' on external commands. 299For this the shell variable HELPDIR should point to a directory containing 300the files generated by the helpfiles script. run-help should be 301unaliased before loading the run-help function. After that this function 302will be executed by the run-help ZLE function which is by default bound 303to ESC-h in emacs mode. 304 305Examples 306-------- 307 308Examples of zsh startup files are located in the subdirectory 309StartupFiles. Examples of zsh functions and scripts are located in 310the subdirectory Functions. Examples of completion control commands 311(compctl) are located in the file Misc/compctl-examples. 312 313Zsh FTP Sites, Web Pages, and Mailing Lists 314------------------------------------------- 315 316The current list of zsh FTP sites, web pages, and mailing lists can be 317found in the META-FAQ. A copy is included in this distribution and is 318available separately at any of the zsh FTP sites. 319 320Common Problems and Frequently Asked Questions 321---------------------------------------------- 322 323Zsh has a list of Frequently Asked Questions (FAQ) maintained by Peter 324Stephenson <pws@zsh.org>. It covers many common problems encountered 325when building, installing, and using zsh. A copy is included in this 326distribution in Etc/FAQ and is available separately at any of the zsh 327ftp sites. 328 329Zsh Maintenance and Bug Reports 330------------------------------- 331 332Zsh is currently maintained by the members of the zsh-workers mailing list 333and coordinated by Peter Stephenson <coordinator@zsh.org>. Please send 334any feedback and bugs reports to <zsh-workers@zsh.org>. 335 336Reports are most helpful if you can reproduce the bug starting zsh with 337the -f option. This skips the execution of local startup files except 338/etc/zshenv. If a bug occurs only when some options set try to locate 339the option which triggers the bug. 340 341There is a script "reporter" in the subdirectory Util which will print out 342your current shell environment/setup. If you cannot reproduce the bug 343with "zsh -f", use this script and include the output from sourcing this 344file. This way, the problem you are reporting can be recreated. 345 346The known bugs in zsh are listed in the file Etc/BUGS. Check this as 347well as the Frequently Asked Questions (FAQ) list before sending a bug 348report. Note that zsh has some features which are not compatible with 349sh but these are not bugs. Most of these incompatibilities go away 350when zsh is invoked as sh or ksh (e.g. using a symbolic link). 351 352If you send a bug report to the list and are not a subscriber, please 353mention this in your message if you want a response. 354 355If you would like to contribute to the development and maintenance of zsh, 356then you should join the zsh-workers mailing list (check the META-FAQ 357for info on this). You should also read the "zsh-development-guide" 358located in the subdirectory Util. 359 360Contributors 361------------ 362 363The people who have contributed to this software project are listed 364in Etc/CONTRIBUTORS. 365