Skip to content

HTTPS clone URL

Subversion checkout URL

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