1----------------- 2THE Z SHELL (ZSH) 3----------------- 4 5Version 6------- 7 8This is version 5.8.1 of the shell. This is a security and bugfix release. 9All zsh installations are encouraged to upgrade as soon as possible. 10 11Note in particular the changes highlighted under "Incompatibilities since 125.8" below. See NEWS for more information. 13 14Installing Zsh 15-------------- 16 17The instructions for compiling zsh are in the file INSTALL. You should 18also check the file MACHINES in the top directory to see if there 19are any special instructions for your particular architecture. 20 21Note in particular the zsh/newuser module that guides new users through 22setting basic shell options without the administrator's intervention. This 23is turned on by default. See the section AUTOMATIC NEW USER CONFIGURATION 24in INSTALL for configuration information. 25 26Features 27-------- 28 29Zsh is a shell with lots of features. For a list of some of these, see the 30file FEATURES, and for the latest changes see NEWS. For more 31details, see the documentation. 32 33Incompatibilities since 5.8 34--------------------------- 35 36PROMPT_SUBST expansion is no longer performed on arguments to prompt- 37expansion sequences such as %F. 38 39Incompatibilities since 5.7.1 40----------------------------- 41 42The history expansion !:1:t2 used to be interpreted such that the 2 43was a separate character added after the history expansion. Now 44it is an argument to the :t modifier. 45 46For example 47 48% echo /my/interesting/path 49% echo !:1:t2 50 51used to echo "path2", but now echoes "interesting/path". 52 53The behaviour of :h has similarly changed. 54 55The behaviour has also changed in forms such as ${foo:t2) and *(:t2), 56but in those cases the previous behaviour was not meaningful. 57 58The vcs_info function VCS_INFO_quilt-dirfind now returns a string value 59by setting $REPLY. Previously it printed the value to standard output. 60This only affects you if you override that function in your dotfiles. 61 62The cd and chdir builtins no longer interpret operands like -1 and +2 as 63stack entries when POSIX_CD is enabled. 64 65Dropping privileges with `unsetopt privileged` may fail (with an error 66message) on some older and uncommon platforms due to library dependency 67changes made in the course of fixing CVE-2019-20044. Please report this 68to the zsh-workers mailing list if your system is affected. See NEWS for 69more. 70 71Incompatibilities between 5.6.2 and 5.7.1 72----------------------------------------- 73 741) vcs_info git: The gen-unapplied-string hook receives the patches in 75order (next to be applied first). This is consistent with the hg 76backend and with one of two contradictory claims in the documentation 77(the other one has been corrected). In zsh through 5.6.2, the patches 78were passed in reverse order, next to be applied being last in the 79array. 80 81The gen-applied-string hook is unaffected; it still receives the patches in 82reverse order, from last applied to first applied. 83 842) The option NO_UNSET now also applies when reading values from 85variables without a preceding '$' sign in shell arithmetic expansion 86and in the double-parentheses and 'let' arithmetic commands. 87 88Incompatibilities between 5.5.1 and 5.6.2 89------------------------------------------ 90 91The completion helper _remote_files, typically used after a hostname 92with scp-style completion, now uses remote-files instead of files as a 93tag. This makes it easier to restrict completions with the tag-order 94style. 95 96Incompatibilities between 5.4.2 and 5.5.1 97----------------------------------------- 98 991) The default build-time maximum nested function depth has been 100decreased from 1000 to 500 based on user experience. However, 101it can now be changed at run time via the variable FUNCNEST. 102If you previously configured the shell to set a different value, 103or to remove the check, this is now reflected in the default 104value of the variable. 105 1062) The syntax 107 108foo=([key]=value) 109 110can be used to set elements of arrays and associative arrays. In the 111unlikely event that you need to set an array by matching files using a 112pattern that starts with a character range followed by '=', you need to 113quote the '=', e.g.: 114 115foo=([aeiou]\=vowel) 116 117This is only required for array values contained within parentheses; 118command line expansion for normal arguments has not changed. 119 1203) The syntax 121 122[[ -o foo ]] 123 124where foo is not the name of a shell option (with optional underscores 125and optional "no" prefix) used to be treated as a syntax error, i.e., 126the enclosing command line or file were aborted. It now emits a warning 127and returns a non-zero exit code. For further details, see the 128documentation of the -o switch in the chapter "Conditional Expressions" 129in the zshmisc(1) manual. 130 131 132Incompatibilities between 5.3.1 and 5.4.2 133----------------------------------------- 134 1351) The default behaviour of code like the following has changed: 136 137 alias foo='noglob foo' 138 foo() { print function body; } 139 140When this is encountered in a start-up file, or other place where input 141was read line by line, "foo" is in command position and is expanded as 142an alias before the function definition takes place. In previous 143versions of the shell, this caused two functions "noglob" and "foo" to 144be defined. Any expansion of an alias in a function definition is 145nearly always an unintended effect, as well as hard to detect, so has 146been made an error. (The option setting NO_MULTI_FUNC_DEF turned this 147case into an error, but did not help with other cases and is off by 148default.) The alternative, of not expanding the alias, was rejected as 149it was more difficult to achieve in the parser and also would silently 150change the shell's behaviur between versions. A new option, 151ALIAS_FUNC_DEF, has been added, which can be set to make the shell 152behave as in previous versions. It is in any case recommended to use 153the "function" keyword, as aliases are not expanded afterwards. 154 1552) It was an undocumented, and largely useless, feature that a function 156autoloaded with an absolute path was searched for along the normal fpath 157(as if the leading / was missing) and, if found, loaded under the full 158name including the leading slash. This has been replaced with the more 159useful feature that the function is searched for only at the given 160absolute path; the name of the function is the base name of the file. 161Note that functions including a non-leading / behave as before, 162e.g. if `dir/name' is found anywhere under a directory in $fpath it is 163loaded as a function named `dir/name'. 164 1653) vcs_info: When neither a set-patch-format nor a gen-applied-string 166(resp. gen-unapplied-string) hook is set, vcs_info now '%'-escapes the 167applied-string (resp. unapplied-string) before interpolating it into the 168patch-format string, to prevent literal `%' signs in the interpolated 169value from being interpreted as prompt escape sequences. If you use 170${vcs_info_msg_0_} in a context other than the shell prompt, you may need 171to undo the escaping with: 172 173 print -v vcs_info_msg_0_ -Pr -- "${vcs_info_msg_0_}" 174 175This is also needed if $vcs_info_msg_0_ is used to set $psvar. 176 1774) functions executed by ZLE widgets no longer have their standard input 178closed, but redirected from /dev/null instead. That still guards 179against user defined widgets inadvertently reading from the tty device, 180and addresses the antisocial behaviour of running a command with its 181stdin closed. 182 1835) [New between 5.4.1 and 5.4.2] In previous versions of the shell, the 184following code: 185 186 () { setopt err_return; false; echo 'oh no' } && true 187 188printed "oh no", as the ERR_RETURN behaviour was suppressed when 189a function was executed on the left hand side of an "&&" list. This was 190undocumented and inconvenient as it is generally more useful to consider 191execution within a function in isolation from its environment. The shell 192now returns from the function on executing `false'. (This is general 193to all functions; an anonymous function is shown here for compactness.) 194 195 196Incompatibilities between 5.0.8 and 5.3 197---------------------------------------- 198 1991) In character classes delimited by "[" and "]" within patterns, whether 200used for filename generation (globbing) or other forms of pattern 201matching, it used not to be possible to quote "-" when used for a range, 202or "^" and "!" when used for negating a character set. The characters can 203now be quoted by any of the standard shell means, but note that 204the "[" and "]" must not be quoted. For example, 205 206 [[ $a = ['a-z'] ]] 207 208matches if the variable a contains just one of the characters "a", "-" 209or "z" only. Previously this would have matched any lower case ASCII 210letter. Note therefore the useful fact that 211 212 [[ $a = ["$cset"] ]] 213 214matches any character contained in the variable "cset". A consequence 215of this change is that variables that should have active ranges need 216(with default zsh options) to be indicated explicitly, e.g. 217 218 cset="a-z" 219 [[ b = [${~cset}] ]] 220 221The "~" causes the "-" character to be active. In sh emulation the 222"~" is unnecessary in this example and double quotes must be used to 223suppress the range behaviour of the "-". 224 2252) The first argument to 'repeat' is now evaluated as an arithmetic 226expression. It was always documented to be an arithmetic expression, but 227until now the decimal integer at the start of the value was used and the 228remainder of the value discarded. This could lead to different behaviour 229if the argument contains non-numeric characters, or if the argument has 230leading zeroes and the OCTAL_ZEROES option is set. 231 2323) For some time the shell has had a POSIX_TRAPS option which determines 233whether the EXIT trap has POSIX behaviour (the trap is only run at shell 234exit) or traditional zsh behaviour (the trap is run once and discarded 235when the enclosing function or shell exits, whichever happens first). 236The use of this option has now been made "sticky" on the EXIT trap --- 237in other words, the setting of the option at the point where the trap is 238set now determines whether the trap has POSIX or traditional zsh 239behaviour. This means that changing the option after the trap was set 240no longer has any effect. 241 242Other aspects of EXIT trap handling have not changed --- there is still 243only one EXIT trap at any point in a programme, so it is not generally 244useful to combine POSIX and non-POSIX behaviour in the same script. 245 2464) There was an undocumented feature dating from the early days of zsh 247that glob qualifiers consisting only of the digits 0 to 7 were treated 248as an octal file mode to "and" with the modes of files being tested. 249This has been removed in order to be more sensitive to syntax errors. 250The "f" qualifier has for many years been the documented way of testing 251file modes; it allows the "and" test ("*(f+1)" is the documented 252equivalent of "*(1)") as well as many other forms. 253 2545) The completion helper function _arguments now escapes both backslashes 255and colons in the values of option arguments when populating the $opt_args 256associative array. Previously, colons were escaped with a backslash but 257backslashes were not themselves escaped with a backslash, which lead to 258ambiguity: '-x foo\:bar' (one argument with a backslashed colon) and 259'-x foo\\ bar' (two arguments, and the first one ends in a backslash) would 260both set $opt_args[-x] to the same value. This example assumes the -x 261option's spec declared two arguments, as in: 262 _arguments : -x:foo:${action}:bar:$action 263 264For the more common case of non-repeatable options that take a single 265argument, completion functions now have to unescape not only colons but 266also backslashes when obtaining the option's argument from $opt_args. 267 2686) Previously, if the function command_not_found_handler was run 269in place of a command-not-found error, and the function returned 270non-zero status, zsh set the status to 127 and printed an error message 271anyway. Now, the status from the handler is retained and no additional 272message is printed. The main reasons for this change are that it was not 273possible to return a non-zero status to the parent shell from a command 274executed as a replacement, and the new implementation is more consistent 275with other shells. 276 2777) The output of "typeset -p" (and synonyms) now takes into account the 278function scope and export state of each parameter. Exported parameters 279are output as "export" commands unless the parameter is also local, and 280other parameters not local to the scope are output with the "-g" option. 281Previously, only "typeset" commands were output, never using "-g". 282 2838) At spelling-correction prompt ($SPROMPT), where the choices offered are 284[nyae], previously <Enter> would be accepted to mean [N] and <Space> and 285<Tab> would be accepted to mean [Y]. Now <Space> and <Tab> are invalid 286choices: typing either of them remains at the prompt. 287 2889) The $ary[i,j] subscript syntax to take a slice of an array behaves 289differently when both i and j are larger than the number of elements in 290the array. When i == j, such a slice always yields an empty array, and 291when i < j it always yields an array of one empty string element. The 292following example illustrates how this differs from past versions. 293 294 nargs() { print $# } 295 a=(one two) 296 for i in 1 2 3 4; do 297 for j in 1 2 3 4 5; do 298 print -n "$i $j => " 299 nargs "${(@)a[i,j]}" 300 done 301 done 302 303 5.2 | 5.3 ** 304 ----------+---------- 305 1 1 => 1 | 1 1 => 1 306 1 2 => 2 | 1 2 => 2 307 1 3 => 2 | 1 3 => 2 308 1 4 => 2 | 1 4 => 2 309 1 5 => 2 | 1 5 => 2 310 2 1 => 0 | 2 1 => 0 311 2 2 => 1 | 2 2 => 1 312 2 3 => 1 | 2 3 => 1 313 2 4 => 1 | 2 4 => 1 314 2 5 => 1 | 2 5 => 1 315 3 1 => 0 | 3 1 => 0 316 3 2 => 0 | 3 2 => 0 317 3 3 => 0 | 3 3 => 0 318 3 4 => 0 | 3 4 => 1 ** 319 3 5 => 0 | 3 5 => 1 ** 320 4 1 => 0 | 4 1 => 0 321 4 2 => 0 | 4 2 => 0 322 4 3 => 0 | 4 3 => 0 323 4 4 => 1 | 4 4 => 0 ** 324 4 5 => 1 | 4 5 => 1 325 326The behaviour of the parameter flag (P) has changed when it appears 327in a nested parameter group, in order to make it more useful in 328such cases. A (P) in the outermost parameter group behaves as 329before. See NEWS for more. 330 331The default behaviour when text is pasted into an X Windows terminal has 332changed significantly (unless you are using a very old terminal emulator 333that doesn't support this mode). Now, the new "bracketed paste mode" 334treats all the pasted text as literal characters. This means, in 335particular, that a newline is simply inserted as a visible newline; you 336need to hit Return on the keyboard to execute the pasted text in one go. 337See the description of zle_bracketed_paste in the zshparams manual for 338more. "unset zle_bracketed_paste" restores the previous behaviour. 339 340As noted in NEWS, the builtins declare, export, float, integer, local, 341readonly and typeset now have corresponding reserved words that provide 342true assignment semantics instead of an approximation by means of normal 343command line arguments. It is hoped that this additional consistency 344provides a more natural interface. However, compatibility with older 345versions of zsh can be obtained by turning off the reserved word 346interface, exposing the builtin interface: 347 348 disable -r declare export float integer local readonly typeset 349 350This is also necessary in the unusual eventuality that the builtins are 351to be overridden by shell functions, since reserved words take 352precedence over functions. 353 35410) For compatilibity with other shells, the syntax 355 356array=([index]=value) 357 358can be used with both assoiative arrays and normal arrays. In the 359unlikely event that you wish to create an array with an entry 360matching a file whose name consists of one of a range of characters 361matched as a [...] expression, followed by an equal sign, followed 362by arbitrary other characters, it is now necessary to quote the equals 363sign. 364 365Incompatibilites between 5.0.7 and 5.0.8 366---------------------------------------- 367 368Various arithmetic operations have changed, in particular with respect 369to the choice of integer or floating point operations. The new 370behaviour is intended to be more consistent, but is not compatible with 371the old. 372 3731) Previously, the modulus operation, `%', implicitly converted the 374operation to integer and output an integer result, even if one 375or both of the arguments were floating point. Now, the C math 376library fmod() operator is used to implement the operation where 377one of the arguments is floating point. For example: 378 379Old behaviour: 380 381% print $(( 5.5 % 2 )) 3821 383 384New behaviour: 385 386% print $(( 5.5 % 2 )) 3871.5 388 389 3902) Previously, assignments to variables assigned the correct type to 391variables declared as floating point or integer, but this type was 392not propagated to the value of the expression, as a C programmer 393would naturally expect. Now, the type of the variable is propagated 394so long as the variable is declared as a numeric type (however this 395happened, e.g. the variable may have been implicitly typed by a 396previous assignment). For example: 397 398Old behaviour: 399 400% integer var 401% print $(( var = 5.5 / 2.0 )) 4022.75 403% print $var 4042 405 406New behaviour: 407 408% integer var 409% print $(( var = 5.5 / 2.0 )) 4102 411% print $var 4122 413 414 4153) Previously, the FORCE_FLOAT option only forced the use of floating 416point in arithmetic expressions for integer constants, i.e. numbers 417typed directly into the expression, but not for variables. Hence 418an operation involving only integer variables (or string variables 419containing integers) was not forced to be performed with floating point 420arithmetic. Now, operations involving variables are also forced to 421floating point. For example: 422 423Old behaviour: 424 425% unsetopt FORCE_FLOAT 426% print $(( 1 / 2 )) 4270 428% integer i=1 j=2 429% print $(( i / j )) 4300 431% setopt FORCE_FLOAT 432% print $(( 1 / 2 )) 4330.5 434% print $(( i / j )) 4350 436 437New behaviour: 438 439% unsetopt FORCE_FLOAT 440% print $(( 1 / 2 )) 4410 442% integer i=1 j=2 443% print $(( i / j )) 4440 445% setopt FORCE_FLOAT 446% print $(( 1 / 2 )) 4470.5 448% print $(( i / j )) 4490.5 450 451 4524) The _git completion used to offer both local and remote heads under the 453tag 'heads'. The tag has now been split into 'heads-local' and 454'heads-remote' in all contexts that existed in 5.0.7. The --fixup/--squash 455context still uses the tag 'heads' (but this may change in a future release). 456 457 458Incompatibilities between 5.0.2 and 5.0.5 459----------------------------------------- 460 461The "zshaddhistory" hook mechanism documented in the zshmisc manual page 462has been upgraded so that a hook returning status 2 causes a history 463line to be saved on the internal history list but not written to the 464history file. Previously any non-zero status return would cause 465the line not to be saved on the history at all. It is recommended 466to use status 1 for this (indeed most shell users would naturally do 467so). 468 469Incompatibilities between 5.0.0 and 5.0.2 470----------------------------------------- 471 472In 5.0.0, the new "sticky" emulation feature was applied to functions 473explicitly declared within an expression following `emulate ... -c', but 474did not apply to functions marked for autoload in that expression. This 475was not documented and experience suggests it was inconvenient, so in 4765.0.2 autoloads also have the sticky property. 477 478In other words, 479 480 emulate zsh -c 'func() { ... }' 481 482behaves the same way in 5.0.0 and 5.0.2, with the function func always being 483run in native zsh emulation regardless of the current option settings. 484However, 485 486 emulate zsh -c 'autoload -Uz func' 487 488behaves differently: in 5.0.0, func was loaded with the options in 489effect at the point where it was first run, and subsequently run with 490whatever options were in effect at that point; in 5.0.2, func is loaded 491with native zsh emulation options and run with those same options. This 492is now the recommended way of ensuring a function is loaded and run with 493a consistent set of options. 494 495Note that the command `autoload -z' has never affected the options 496applied when the function is loaded or run, only the effect of the 497KSH_AUTOLOAD option at the point the function is loaded. 498 499Possible incompatibilities between 4.2 and 5.0 500---------------------------------------------- 501 502Here are some incompatibilities in the shell since the 4.2 series of 503releases. It is hoped most users will not be adversely affected by these. 504 505In previous releases of the shell, builtin commands and precommand 506modifiers that did not accept options also did not recognize the 507argument "--" as marking the end of option processing without being 508considered an argument. This was not documented and was incompatible 509with other shells. All such commands now handle this syntax. 510 511The configuration option --enable-lfs to enable large file support has 512been replaced by autoconf's standard --enable-largefile mechanism. 513As this is usually used whenever necessary, this won't usually 514be noticeable; however, anyone configuring with --disable-lfs 515should configure with --disable-largefile instead. 516 517The configuration option --with-curses-terminfo has been replaced 518by the option --with-term-lib="LIBS" where LIBS is a space-separated 519list of libraries to search for termcap and curses features. 520 521The option SH_WORD_SPLIT, used in Bourne/Korn/Posix shell compatibility 522mode, has been made more like other shells in the case of substitutions of 523the form ${1+"$@"} (a common trick used to work around problems in older 524Bourne shells) or any of the related forms with the + replaced by - or = 525with an optional colon preceding. Previously, with SH_WORD_SPLIT in 526effect, this expression would cause splitting on all white space in the 527shell arguments. (This was always regarded as a bug but was long-standing 528behaviour.) Now it is treated identically to "$@". The same change 529applies to expressions with forced splitting such as ${=1+"$@"}, but 530otherwise the case where SH_WORD_SPLIT is not set is unaffected. 531 532Debug traps (`trap ... DEBUG' or the function TRAPDEBUG) now run by default 533before the command to which they refer instead of after. This is almost 534always the right behaviour for the intended purpose of debugging and is 535consistent with recent versions of other shells. The option 536DEBUG_BEFORE_CMD can be unset to revert to the previous behaviour. 537 538Previously, process substitutions of the form =(...), <(...) and >(...) 539were only handled if they appeared as separate command arguments. 540(However, the latter two forms caused the current argument to be 541terminated and a new one started even if they occurred in the middle of 542a string.) Now all three may be followed by other strings, and the 543latter two may also be preceded by other strings. Remaining 544limitations on their use (to reduce incompatibilities to a minimum) 545are documented in the zshexpn.1 manual. 546 547In previous versions of the shell it was possible to use index 0 in an 548array or string subscript to refer to the same element as index 1 if the 549option KSH_ARRAYS was not in effect. This was a limited approximation to 550the full KSH_ARRAYS handling and so was not very useful. In this version 551of the shell, this behaviour is only provided when the option 552KSH_ZERO_SUBSCRIPT is set. Note that despite the name this does not provide 553true compatibility with ksh or other shells and KSH_ARRAYS should still be 554used for that purpose. By default, the option is not set; an array 555subscript that evaluates to 0 returns an empty string or array element and 556attempts to write to an array or string range including only a zero 557subscript are treated as an error. Writes to otherwise valid ranges that 558also include index zero are allowed; hence for example the assignment 559 array[(R)notfound,(r)notfound]=() 560(where the string "notfound" does not match an element in $array) sets the 561entire array to be empty, as in previous versions of the shell. 562KSH_ZERO_SUBSCRIPT is irrelevant when KSH_ARRAYS is set. Also as in previous 563versions, attempts to write to non-existent elements at the end of an array 564cause the array to be suitably extended. This difference means that, for 565example 566 array[(R)notfound]=(replacement) 567is an error if KSH_ZERO_SUBSCRIPT is not set (new behaviour), while 568 array[(r)notfound]=(replacement) 569causes the given value to be appended to the array (same behaviour as 570previous versions). 571 572The "exec" precommand modifier now takes various options for compatibility 573with other shells. This means that whereas "exec -prog" previously 574tried to execute a command name "-prog", it will now report an error 575in option handling. "exec -- -prog" will execute "-prog". If 576the option EQUALS is set, as it is by default in zsh's native mode, 577"exec =-prog" behaves the same way in all versions of zsh provided 578the command can be found. 579 580The "unset" builtin now does not regard the unsetting of non-existent 581variables as an error, so can still return status 0 (depending on the 582handling of other arguments). This appears to be the standard shell 583behaviour. 584 585The variable BAUD is no longer set automatically by the shell. 586In previous versions it was set to the baud rate reported by 587the terminal driver in order to initialise the line editor's 588compensation mechanism for slow baud rates. However, the baud 589rate so reported is very rarely related to the limiting speed of 590screen updates on modern systems. Users who need the compensation 591mechanism should set BAUD to an appropriate rate by hand. 592 593The variable HOME is no longer set by the shell if zsh is emulating any 594other shell at startup; it must be present in the environment or set 595subsequently by the user. It is valid for the variable to be unset. 596 597If the shell starts in a mode where it is emulating another shell 598(typically because the base name of the shell was "sh" or another known 599shell), the "repeat" syntax is not available by default, to avoid clashes 600with external commands, but the "ulimit" command is available by default. 601"limit", "sched" and "unlimit" are not available by default in such modes: 602this has been the case for many versions but is now documented for the 603first time. (Users should note that emulation modes are not designed for 604backwards compatibility with previous versions of zsh, but to maximise 605compatibility with other shells, hence it is not safe to assume emulation 606modes will behave consistently between zsh versions.) 607 608Parameter substitutions in the form ${param//#%search/replace} match 609against "search" anchored at both ends of the parameter value. Previously 610this syntax would have matched against "%search", anchored only at the head 611of the value. The form ${param//#$search/replace} where the value 612$search starts with "%" considers the "%" to be part of the search 613string as before. 614 615Configure attempts to decide if multibyte characters are supported by the 616system and if so sets the effect of --enable-multibyte, unless 617--disable-multibyte was passed on the command line. When 618--enable-multibyte is in effect, the MULTIBYTE shell option is on by 619default; this causes many operations to recognise characters in the current 620locale. (Most typically this is used for a UTF-8 character set but the 621shell will work with any character set provided by the system where 622individual octets are either US ASCII characters or have the top bit set.) 623Older versions of the shell always assumed a character was one byte; this 624remains the case if --disable-multibyte is in effect or if the MULTIBYTE 625option is unset. In some places the width of characters will be taken into 626account where previously a raw string length was used; this is transparent 627in calculations of screen position, but also occurs, for example, in 628calculations of padding width. Note that MULTIBYTE is not automatically 629set when emulating Bourne- and POSIX-style shells; for interactive use of 630these emulations it may be necessary to set it by hand. Note also that the 631option COMBINING_CHARS is not set by default due to difficulties detecting 632the ability of the terminal to display combining characters correctly; MAC 633users in particular will probably wish to set this option. 634 635Zsh has previously been lax about whether it allows octets with the 636top bit set to be part of a shell identifier. Older versions of the shell 637assumed all such octets were allowed in identifiers, however the POSIX 638standard does not allow such characters in identifiers. The older 639behaviour is still obtained with --disable-multibyte in effect. 640With --enable-multibyte in effect (see previous paragraph) there are three 641possible cases: 642 MULTIBYTE option unset: only ASCII characters are allowed; the 643 shell does not attempt to identify non-ASCII characters at all. 644 MULTIBYTE option set, POSIX_IDENTIFIERS option unset: in addition 645 to the POSIX characters, any alphanumeric characters in the 646 local character set are allowed. Note that scripts and functions that 647 take advantage of this are non-portable; however, this is in the spirit 648 of previous versions of the shell. Note also that the options must 649 be set before the shell parses the script or function; setting 650 them during execution is not sufficient. 651 MULITBYTE option set, POSIX_IDENTIFIERS set: only ASCII characters 652 are allowed in identifiers even though the shell will recognise 653 alphanumeric multibyte characters. 654 655The sched builtin now keeps entries in time order. This means that 656after adding an entry the index of an existing entry used for deletion 657may change, if that entry had a later time than the new entry. However, 658deleting a entry with a later time will now never change the index of an 659entry with an earlier time, which could happen with the previous method. 660 661The completion style pine-directory must now be set to use completion 662for PINE mailbox folders; previously it had the default ~/mail. This 663change was necessary because otherwise recursive directories under 664~/mail were searched by default, which could be a considerable unnecessary 665hit for anyone not using PINE. The previous default can be restored with: 666 zstyle ':completion:*' pine-directory ~/mail 667 668The completion style fake-files now allows patterns as directories, 669for example the value '/home/*:.snapshot' is now valid. This will 670only cause problems in the unlikely event that a directory in the style 671has a pattern character in it. 672 673The default maximum function depth (configurable with 674--enable-max-function-depth) has been decreased to 1000 from 4096. The 675previous value was observed to be small enough that crashes still occurred 676on some fairly common PC configurations. This change is only likely to 677affect some highly specialised uses of the shell. 678 679The variables HISTCHARS and histchars now reject any attempt to 680set non-ASCII characters for history or comments. Multibyte characters 681have never worked and the most consistent change was to restrict the 682set to portable characters only. 683 684Writers of add-on modules should note that the API has changed 685significantly to allow user control of individual features provided by 686modules. See the documentation for zmodload -F and 687Etc/zsh-development-guide, in that order. 688 689Documentation 690------------- 691 692There are a number of documents about zsh in this distribution: 693 694Doc/Zsh/*.yo The master source for the zsh documentation is written in 695 yodl. Yodl is a document language written by Karel Kubat. 696 It is not required by zsh but it is a nice program so you 697 might want to get it anyway, especially if you are a zsh 698 developer. It can be downloaded from 699 https://fbb-git.github.io/yodl/ 700 701Doc/zsh*.1 Man pages in nroff format. These will be installed 702 by "make install.man" or "make install". By default, 703 these will be installed in /usr/local/man/man1, although 704 you can change this with the --mandir option to configure 705 or editing the user configuration section of the top level 706 Makefile. 707 708Doc/zsh.texi Everything the man pages have, but in texinfo format. These 709 will be installed by "make install.info" or "make install". 710 By default, these will be installed in /usr/local/info, 711 although you can change this with the --infodir option to 712 configure or editing the user configuration section of the 713 top level Makefile. Version 4.0 or above of the 714 Texinfo tools are recommended for processing this file. 715 716Also included in the distribution are: 717 718Doc/intro.ms An introduction to zsh in troff format using the ms 719 macros. This document explains many of the features 720 that make zsh more equal than other shells. 721 Unfortunately this is based on zsh-2.5 so some examples 722 may not work without changes but it is still a good 723 introduction. 724 725For more information, see the website, as described in the META-FAQ. 726 727If you do not have the necessary tools to process these documents, PDF, 728Info and DVI versions are available in the separate file zsh-doc.tar.gz at 729the archive sites listed in the META-FAQ. 730 731The distribution also contains a Perl script in Utils/helpfiles which 732can be used to extract the descriptions of builtin commands from the 733zshbuiltins manual page. See the comments at the beginning of the 734script about its usage. The files created by this script can be used 735by example function run-help located in the subdirectory Functions/Misc to 736show information about zsh builtins and run `man' on external commands. 737For this the shell variable HELPDIR should point to a directory containing 738the files generated by the helpfiles script. run-help should be 739unaliased before loading the run-help function. After that this function 740will be executed by the run-help ZLE function which is by default bound 741to ESC-h in emacs mode. 742 743Examples 744-------- 745 746Examples of zsh startup files are located in the subdirectory 747StartupFiles. Examples of zsh functions and scripts are located in 748the subdirectory Functions. Examples of completion control commands 749(compctl) are located in the file Misc/compctl-examples. 750 751Zsh FTP Sites, Web Pages, and Mailing Lists 752------------------------------------------- 753 754The current list of zsh FTP sites, web pages, and mailing lists can be 755found in the META-FAQ. A copy is included in this distribution and is 756available separately at any of the zsh FTP sites. 757 758Common Problems and Frequently Asked Questions 759---------------------------------------------- 760 761Zsh has a list of Frequently Asked Questions (FAQ) maintained by Peter 762Stephenson <pws@zsh.org>. It covers many common problems encountered 763when building, installing, and using zsh. A copy is included in this 764distribution in Etc/FAQ and is available separately at any of the zsh 765ftp sites. 766 767Zsh Maintenance and Bug Reports 768------------------------------- 769 770Zsh is currently maintained by the members of the zsh-workers mailing list 771and coordinated by Peter Stephenson <coordinator@zsh.org>. Please send 772any feedback and bugs reports to <zsh-workers@zsh.org>. 773 774Reports are most helpful if you can reproduce the bug starting zsh with 775the -f option. This skips the execution of local startup files except 776/etc/zshenv. If a bug occurs only when some options set try to locate 777the option which triggers the bug. 778 779There is a script "reporter" in the subdirectory Util which will print out 780your current shell environment/setup. If you cannot reproduce the bug 781with "zsh -f", use this script and include the output from sourcing this 782file. This way, the problem you are reporting can be recreated. 783 784The known bugs in zsh are listed in the file Etc/BUGS. Check this as 785well as the Frequently Asked Questions (FAQ) list before sending a bug 786report. Note that zsh has some features which are not compatible with 787sh but these are not bugs. Most of these incompatibilities go away 788when zsh is invoked as sh or ksh (e.g. using a symbolic link). 789 790If you send a bug report to the list and are not a subscriber, please 791mention this in your message if you want a response. 792 793If you would like to contribute to the development and maintenance of zsh, 794then you should join the zsh-workers mailing list (check the META-FAQ 795for info on this). You should also read the "zsh-development-guide" 796located in the subdirectory Etc. 797 798Contributors 799------------ 800 801The people who have contributed to this software project are listed 802in Etc/CONTRIBUTORS. 803