xref: /zsh/
NameDateSize

..16-Mar-201612 KiB

.distfiles25-Aug-201468

.editorconfig27-Oct-2014170

.gitignore09-Nov-20152 KiB

.preconfig29-Dec-201258

aclocal.m429-Dec-20122.3 KiB

aczsh.m429-Dec-201219.1 KiB

ChangeLog14-Dec-2015250 KiB

Completion/24-Jun-20154 KiB

Config/09-Dec-20154 KiB

config.guess29-Dec-201243.9 KiB

config.sub29-Dec-201233.6 KiB

configure.ac25-Sep-2015101.6 KiB

Doc/16-Nov-20154 KiB

Etc/30-Nov-20154 KiB

FEATURES29-Dec-20125.2 KiB

Functions/25-Aug-20144 KiB

INSTALL20-Dec-201329.3 KiB

install-sh29-Dec-201212.9 KiB

LICENCE10-Jan-20141.9 KiB

MACHINES12-Oct-20157.4 KiB

Makefile.in30-Nov-20135.2 KiB

Misc/02-Oct-20144 KiB

mkinstalldirs29-Dec-20123.5 KiB

NEWS20-Nov-201551.3 KiB

README30-Nov-201522.3 KiB

Scripts/25-Aug-20144 KiB

Src/10-Dec-20154 KiB

StartupFiles/25-Aug-20144 KiB

Test/11-Dec-20154 KiB

Util/11-Aug-20154 KiB

README

1-----------------
2THE Z SHELL (ZSH)
3-----------------
4
5Version
6-------
7
8This is version 5.2 of the shell.  This is a stable release.  There are
9a few visible improvements since 5.1.1 as well as many bugfixes.  Note
10in particular the changs highlighted under "Incompatibilites
11between 5.1 and 5.2" below.  See NEWS for more information.
12
13Installing Zsh
14--------------
15
16The instructions for compiling zsh are in the file INSTALL.  You should
17also check the file MACHINES in the top directory to see if there
18are any special instructions for your particular architecture.
19
20Note in particular the zsh/newuser module that guides new users through
21setting basic shell options without the administrator's intervention.  This
22is turned on by default.  See the section AUTOMATIC NEW USER CONFIGURATION
23in INSTALL for configuration information.
24
25Features
26--------
27
28Zsh is a shell with lots of features.  For a list of some of these, see the
29file FEATURES, and for the latest changes see NEWS.  For more
30details, see the documentation.
31
32Incompatibilities between 5.1 and 5.2
33-------------------------------------
34
35The behaviour of the parameter flag (P) has changed when it appears
36in a nested parameter group, in order to make it more useful in
37such cases.  A (P) in the outermost parameter group behaves as
38before.  See NEWS for more.
39
40Incompatibilities between 5.0.8 and 5.1
41---------------------------------------
42
43The default behaviour when text is pasted into an X Windows terminal has
44changed significantly (unless you are using a very old terminal emulator
45that doesn't support this mode).  Now, the new "bracketed paste mode"
46treats all the pasted text as literal characters.  This means, in
47particular, that a newline is simply inserted as a visible newline; you
48need to hit Return on the keyboard to execute the pasted text in one go.
49See the description of zle_bracketed_paste in the zshparams manual for
50more.  "unset zle_bracketed_paste" restores the previous behaviour.
51
52As noted in NEWS, the builtins declare, export, float, integer, local,
53readonly and typeset now have corresponding reserved words that provide
54true assignment semantics instead of an approximation by means of normal
55command line arguments.  It is hoped that this additional consistency
56provides a more natural interface.  However, compatibility with older
57versions of zsh can be obtained by turning off the reserved word
58interface, exposing the builtin interface:
59
60  disable -r declare export float integer local readonly typeset
61
62This is also necessary in the unusual eventuality that the builtins are
63to be overridden by shell functions, since reserved words take
64precedence over functions.
65
66Incompatibilites between 5.0.7 and 5.0.8
67----------------------------------------
68
69Various arithmetic operations have changed, in particular with respect
70to the choice of integer or floating point operations.  The new
71behaviour is intended to be more consistent, but is not compatible with
72the old.
73
741) Previously, the modulus operation, `%', implicitly converted the
75operation to integer and output an integer result, even if one
76or both of the arguments were floating point.  Now, the C math
77library fmod() operator is used to implement the operation where
78one of the arguments is floating point.  For example:
79
80Old behavour:
81
82% print $(( 5.5 % 2 ))
831
84
85New behaviour:
86
87% print $(( 5.5 % 2 ))
881.5
89
90
912) Previously, assignments to variables assigned the correct type to
92variables declared as floating point or integer, but this type was
93not propagated to the value of the expression, as a C programmer
94would naturally expect.  Now, the type of the variable is propagated
95so long as the variable is declared as a numeric type (however this
96happened, e.g. the variable may have been implicitly typed by a
97previous assignment).  For example:
98
99Old behaviour:
100
101% integer var
102% print $(( var = 5.5 / 2.0 ))
1032.75
104% print $var
1052
106
107New behaviour:
108
109% integer var
110% print $(( var = 5.5 / 2.0 ))
1112
112% print $var
1132
114
115
1163) Previously, the FORCE_FLOAT option only forced the use of floating
117point in arithmetic expressions for integer constants, i.e. numbers
118typed directly into the expression, but not for variables.  Hence
119an operation involving only integer variables (or string variables
120containing integers) was not forced to be performed with floating point
121arithmetic.  Now, operations involving variables are also forced to
122floating point.  For example:
123
124Old behaviour:
125
126% unsetopt FORCE_FLOAT
127% print $(( 1 / 2 ))
1280
129% integer i=1 j=2
130% print $(( i / j ))
1310
132% setopt FORCE_FLOAT
133% print $(( 1 / 2 ))
1340.5
135% print $(( i / j ))
1360
137
138New behaviour:
139
140% unsetopt FORCE_FLOAT
141% print $(( 1 / 2 ))
1420
143% integer i=1 j=2
144% print $(( i / j ))
1450
146% setopt FORCE_FLOAT
147% print $(( 1 / 2 ))
1480.5
149% print $(( i / j ))
1500.5
151
152
1534) The _git completion used to offer both local and remote heads under the
154tag 'heads'.  The tag has now been split into 'heads-local' and
155'heads-remote' in all contexts that existed in 5.0.7.  The --fixup/--squash
156context still uses the tag 'heads' (but this may change in a future release).
157
158
159Incompatibilities between 5.0.2 and 5.0.5
160-----------------------------------------
161
162The "zshaddhistory" hook mechanism documented in the zshmisc manual page
163has been upgraded so that a hook returning status 2 causes a history
164line to be saved on the internal history list but not written to the
165history file.  Previously any non-zero status return would cause
166the line not to be saved on the history at all.  It is recommended
167to use status 1 for this (indeed most shell users would naturally do
168so).
169
170Incompatibilities between 5.0.0 and 5.0.2
171-----------------------------------------
172
173In 5.0.0, the new "sticky" emulation feature was applied to functions
174explicitly declared within an expression following `emulate ... -c', but
175did not apply to functions marked for autoload in that expression.  This
176was not documented and experience suggests it was inconvenient, so in
1775.0.2 autoloads also have the sticky property.
178
179In other words,
180
181  emulate zsh -c 'func() { ... }'
182
183behaves the same way in 5.0.0 and 5.0.2, with the function func always being
184run in native zsh emulation regardless of the current option settings.
185However,
186
187  emulate zsh -c 'autoload -Uz func'
188
189behaves differently: in 5.0.0, func was loaded with the options in
190effect at the point where it was first run, and subsequently run with
191whatever options were in effect at that point; in 5.0.2, func is loaded
192with native zsh emulation options and run with those same options.  This
193is now the recommended way of ensuring a function is loaded and run with
194a consistent set of options.
195
196Note that the command `autoload -z' has never affected the options
197applied when the function is loaded or run, only the effect of the
198KSH_AUTOLOAD option at the point the function is loaded.
199
200Possible incompatibilities between 4.2 and 5.0
201----------------------------------------------
202
203Here are some incompatibilities in the shell since the 4.2 series of
204releases.  It is hoped most users will not be adversely affected by these.
205
206In previous releases of the shell, builtin commands and precommand
207modifiers that did not accept options also did not recognize the
208argument "--" as marking the end of option processing without being
209considered an argument.  This was not documented and was incompatible
210with other shells.  All such commands now handle this syntax.
211
212The configuration option --enable-lfs to enable large file support has
213been replaced by autoconf's standard --enable-largefile mechanism.
214As this is usually used whenever necessary, this won't usually
215be noticeable; however, anyone configuring with --disable-lfs
216should configure with --disable-largefile instead.
217
218The configuration option --with-curses-terminfo has been replaced
219by the option --with-term-lib="LIBS" where LIBS is a space-separated
220list of libraries to search for termcap and curses features.
221
222The option SH_WORD_SPLIT, used in Bourne/Korn/Posix shell compatibility
223mode, has been made more like other shells in the case of substitutions of
224the form ${1+"$@"} (a common trick used to work around problems in older
225Bourne shells) or any of the related forms with the + replaced by - or =
226with an optional colon preceding.  Previously, with SH_WORD_SPLIT in
227effect, this expression would cause splitting on all white space in the
228shell arguments.  (This was always regarded as a bug but was long-standing
229behaviour.)  Now it is treated identically to "$@".  The same change
230applies to expressions with forced splitting such as ${=1+"$@"}, but
231otherwise the case where SH_WORD_SPLIT is not set is unaffected.
232
233Debug traps (`trap ... DEBUG' or the function TRAPDEBUG) now run by default
234before the command to which they refer instead of after.  This is almost
235always the right behaviour for the intended purpose of debugging and is
236consistent with recent versions of other shells.  The option
237DEBUG_BEFORE_CMD can be unset to revert to the previous behaviour.
238
239Previously, process substitutions of the form =(...), <(...) and >(...)
240were only handled if they appeared as separate command arguments.
241(However, the latter two forms caused the current argument to be
242terminated and a new one started even if they occurred in the middle of
243a string.)  Now all three may be followed by other strings, and the
244latter two may also be preceded by other strings.  Remaining
245limitations on their use (to reduce incompatibilities to a minimum)
246are documented in the zshexpn.1 manual.
247
248In previous versions of the shell it was possible to use index 0 in an
249array or string subscript to refer to the same element as index 1 if the
250option KSH_ARRAYS was not in effect.  This was a limited approximation to
251the full KSH_ARRAYS handling and so was not very useful.  In this version
252of the shell, this behaviour is only provided when the option
253KSH_ZERO_SUBSCRIPT is set.  Note that despite the name this does not provide
254true compatibility with ksh or other shells and KSH_ARRAYS should still be
255used for that purpose.  By default, the option is not set; an array
256subscript that evaluates to 0 returns an empty string or array element and
257attempts to write to an array or string range including only a zero
258subscript are treated as an error.  Writes to otherwise valid ranges that
259also include index zero are allowed; hence for example the assignment
260  array[(R)notfound,(r)notfound]=()
261(where the string "notfound" does not match an element in $array) sets the
262entire array to be empty, as in previous versions of the shell.
263KSH_ZERO_SUBSCRIPT is irrelevant when KSH_ARRAYS is set.  Also as in previous
264versions, attempts to write to non-existent elements at the end of an array
265cause the array to be suitably extended.  This difference means that, for
266example
267  array[(R)notfound]=(replacement)
268is an error if KSH_ZERO_SUBSCRIPT is not set (new behaviour), while
269  array[(r)notfound]=(replacement)
270causes the given value to be appended to the array (same behaviour as
271previous versions).
272
273The "exec" precommand modifier now takes various options for compatibility
274with other shells.  This means that whereas "exec -prog" previously
275tried to execute a command name "-prog", it will now report an error
276in option handling.  "exec -- -prog" will execute "-prog".  If
277the option EQUALS is set, as it is by default in zsh's native mode,
278"exec =-prog" behaves the same way in all versions of zsh provided
279the command can be found.
280
281The "unset" builtin now does not regard the unsetting of non-existent
282variables as an error, so can still return status 0 (depending on the
283handling of other arguments).  This appears to be the standard shell
284behaviour.
285
286The variable BAUD is no longer set automatically by the shell.
287In previous versions it was set to the baud rate reported by
288the terminal driver in order to initialise the line editor's
289compensation mechanism for slow baud rates.  However, the baud
290rate so reported is very rarely related to the limiting speed of
291screen updates on modern systems.  Users who need the compensation
292mechanism should set BAUD to an appropriate rate by hand.
293
294The variable HOME is no longer set by the shell if zsh is emulating any
295other shell at startup; it must be present in the environment or set
296subsequently by the user.  It is valid for the variable to be unset.
297
298If the shell starts in a mode where it is emulating another shell
299(typically because the base name of the shell was "sh" or another known
300shell), the "repeat" syntax is not available by default, to avoid clashes
301with external commands, but the "ulimit" command is available by default.
302"limit", "sched" and "unlimit" are not available by default in such modes:
303this has been the case for many versions but is now documented for the
304first time.  (Users should note that emulation modes are not designed for
305backwards compatibility with previous versions of zsh, but to maximise
306compatibility with other shells, hence it is not safe to assume emulation
307modes will behave consistently between zsh versions.)
308
309Parameter substitutions in the form ${param//#%search/replace} match
310against "search" anchored at both ends of the parameter value.  Previously
311this syntax would have matched against "%search", anchored only at the head
312of the value.  The form ${param//#$search/replace} where the value
313$search starts with "%" considers the "%" to be part of the search
314string as before.
315
316Configure attempts to decide if multibyte characters are supported by the
317system and if so sets the effect of --enable-multibyte, unless
318--disable-multibyte was passed on the command line.  When
319--enable-multibyte is in effect, the MULTIBYTE shell option is on by
320default; this causes many operations to recognise characters in the current
321locale.  (Most typically this is used for a UTF-8 character set but the
322shell will work with any character set provided by the system where
323individual octets are either US ASCII characters or have the top bit set.)
324Older versions of the shell always assumed a character was one byte; this
325remains the case if --disable-multibyte is in effect or if the MULTIBYTE
326option is unset.  In some places the width of characters will be taken into
327account where previously a raw string length was used; this is transparent
328in calculations of screen position, but also occurs, for example, in
329calculations of padding width.  Note that MULTIBYTE is not automatically
330set when emulating Bourne- and POSIX-style shells; for interactive use of
331these emulations it may be necessary to set it by hand.  Note also that the
332option COMBINING_CHARS is not set by default due to difficulties detecting
333the ability of the terminal to display combining characters correctly; MAC
334users in particular will probably wish to set this option.
335
336Zsh has previously been lax about whether it allows octets with the
337top bit set to be part of a shell identifier.  Older versions of the shell
338assumed all such octets were allowed in identifiers, however the POSIX
339standard does not allow such characters in identifiers.  The older
340behaviour is still obtained with --disable-multibyte in effect.
341With --enable-multibyte in effect (see previous paragraph) there are three
342possible cases:
343  MULTIBYTE option unset:  only ASCII characters are allowed; the
344    shell does not attempt to identify non-ASCII characters at all.
345  MULTIBYTE option set, POSIX_IDENTIFIERS option unset: in addition
346    to the POSIX characters, any alphanumeric characters in the
347    local character set are allowed.  Note that scripts and functions that
348    take advantage of this are non-portable; however, this is in the spirit
349    of previous versions of the shell.  Note also that the options must
350    be set before the shell parses the script or function; setting
351    them during execution is not sufficient.
352  MULITBYTE option set, POSIX_IDENTIFIERS set:  only ASCII characters
353    are allowed in identifiers even though the shell will recognise
354    alphanumeric multibyte characters.
355
356The sched builtin now keeps entries in time order.  This means that
357after adding an entry the index of an existing entry used for deletion
358may change, if that entry had a later time than the new entry.  However,
359deleting a entry with a later time will now never change the index of an
360entry with an earlier time, which could happen with the previous method.
361
362The completion style pine-directory must now be set to use completion
363for PINE mailbox folders; previously it had the default ~/mail.  This
364change was necessary because otherwise recursive directories under
365~/mail were searched by default, which could be a considerable unnecessary
366hit for anyone not using PINE.  The previous default can be restored with:
367  zstyle ':completion:*' pine-directory ~/mail
368
369The completion style fake-files now allows patterns as directories,
370for example the value '/home/*:.snapshot' is now valid.  This will
371only cause problems in the unlikely event that a directory in the style
372has a pattern character in it.
373
374The default maximum function depth (configurable with
375--enable-max-function-depth) has been decreased to 1000 from 4096.  The
376previous value was observed to be small enough that crashes still occurred
377on some fairly common PC configurations.  This change is only likely to
378affect some highly specialised uses of the shell.
379
380The variables HISTCHARS and histchars now reject any attempt to
381set non-ASCII characters for history or comments.  Multibyte characters
382have never worked and the most consistent change was to restrict the
383set to portable characters only.
384
385Writers of add-on modules should note that the API has changed
386significantly to allow user control of individual features provided by
387modules.  See the documentation for zmodload -F and
388Etc/zsh-development-guide, in that order.
389
390Documentation
391-------------
392
393There are a number of documents about zsh in this distribution:
394
395Doc/Zsh/*.yo	The master source for the zsh documentation is written in
396		yodl.  Yodl is a document language written by Karel Kubat.
397		It is not required by zsh but it is a nice program so you
398		might want to get it anyway, especially if you are a zsh
399		developer.  It can be downloaded from
400		https://fbb-git.github.io/yodl/
401
402Doc/zsh*.1	Man pages in nroff format.  These will be installed
403		by "make install.man" or "make install".  By default,
404		these will be installed in /usr/local/man/man1, although
405		you can change this with the --mandir option to configure
406		or editing the user configuration section of the top level
407		Makefile.
408
409Doc/zsh.texi	Everything the man pages have, but in texinfo format.  These
410		will be installed by "make install.info" or "make install".
411		By default, these will be installed in /usr/local/info,
412		although you can change this with the --infodir option to
413		configure or editing the user configuration section of the
414		top level Makefile.  Version 4.0 or above of the
415		Texinfo tools are recommended for processing this file.
416
417Also included in the distribution are:
418
419Doc/intro.ms	An introduction to zsh in troff format using the ms
420		macros.  This document explains many of the features
421		that make zsh more equal than other shells.
422		Unfortunately this is based on zsh-2.5 so some examples
423		may not work without changes but it is still a good
424		introduction.
425
426For more information, see the website, as described in the META-FAQ.
427
428If you do not have the necessary tools to process these documents, PDF,
429Info and DVI versions are available in the separate file zsh-doc.tar.gz at
430the archive sites listed in the META-FAQ.
431
432The distribution also contains a Perl script in Utils/helpfiles which
433can be used to extract the descriptions of builtin commands from the
434zshbuiltins manual page.  See the comments at the beginning of the
435script about its usage.  The files created by this script can be used
436by example function run-help located in the subdirectory Functions/Misc to
437show information about zsh builtins and run `man' on external commands.
438For this the shell variable HELPDIR should point to a directory containing
439the files generated by the helpfiles script.  run-help should be
440unaliased before loading the run-help function.  After that this function
441will be executed by the run-help ZLE function which is by default bound
442to ESC-h in emacs mode.
443
444Examples
445--------
446
447Examples of zsh startup files are located in the subdirectory
448StartupFiles.  Examples of zsh functions and scripts are located in
449the subdirectory Functions.  Examples of completion control commands
450(compctl) are located in the file Misc/compctl-examples.
451
452Zsh FTP Sites, Web Pages, and Mailing Lists
453-------------------------------------------
454
455The current list of zsh FTP sites, web pages, and mailing lists can be
456found in the META-FAQ.  A copy is included in this distribution and is
457available separately at any of the zsh FTP sites.
458
459Common Problems and Frequently Asked Questions
460----------------------------------------------
461
462Zsh has a list of Frequently Asked Questions (FAQ) maintained by Peter
463Stephenson <pws@zsh.org>.  It covers many common problems encountered
464when building, installing, and using zsh.  A copy is included in this
465distribution in Etc/FAQ and is available separately at any of the zsh
466ftp sites.
467
468Zsh Maintenance and Bug Reports
469-------------------------------
470
471Zsh is currently maintained by the members of the zsh-workers mailing list
472and coordinated by Peter Stephenson <coordinator@zsh.org>.  Please send
473any feedback and bugs reports to <zsh-workers@zsh.org>.
474
475Reports are most helpful if you can reproduce the bug starting zsh with
476the -f option.  This skips the execution of local startup files except
477/etc/zshenv.  If a bug occurs only when some options set try to locate
478the option which triggers the bug.
479
480There is a script "reporter" in the subdirectory Util which will print out
481your current shell environment/setup.  If you cannot reproduce the bug
482with "zsh -f", use this script and include the output from sourcing this
483file.  This way, the problem you are reporting can be recreated.
484
485The known bugs in zsh are listed in the file Etc/BUGS.  Check this as
486well as the Frequently Asked Questions (FAQ) list before sending a bug
487report.  Note that zsh has some features which are not compatible with
488sh but these are not bugs.  Most of these incompatibilities go away
489when zsh is invoked as sh or ksh (e.g. using a symbolic link).
490
491If you send a bug report to the list and are not a subscriber, please
492mention this in your message if you want a response.
493
494If you would like to contribute to the development and maintenance of zsh,
495then you should join the zsh-workers mailing list (check the META-FAQ
496for info on this).  You should also read the "zsh-development-guide"
497located in the subdirectory Etc.
498
499Contributors
500------------
501
502The people who have contributed to this software project are listed
503in Etc/CONTRIBUTORS.
504