diff options
Diffstat (limited to 'Etc/FAQ')
| -rw-r--r-- | Etc/FAQ | 257 |
1 files changed, 210 insertions, 47 deletions
@@ -1,15 +1,15 @@ Archive-Name: unix-faq/shell/zsh -Last-Modified: 2015/05/31 +Last-Modified: 2020/08/08 Submitted-By: coordinator@zsh.org (Peter Stephenson) <coordinator@zsh.org (Peter Stephenson)> Posting-Frequency: Monthly -Copyright: (C) P.W. Stephenson, 1995--2016 (see end of document) +Copyright: (C) P.W. Stephenson, 1995--2020 (see end of document) This document contains a list of frequently-asked (or otherwise significant) questions concerning the Z-shell, a command interpreter for many UNIX systems which is freely available to anyone with FTP access. Zsh is among the most powerful freely available Bourne-like -shell for interactive use. +shells for interactive use. If you have never heard of `sh', `csh' or `ksh', then you are probably better off to start by reading a general introduction to UNIX @@ -17,7 +17,7 @@ rather than this document. If you just want to know how to get your hands on the latest version, skip to question 1.6; if you want to know what to do with -insoluble problems, go to 5.2. +insoluble problems, go to 6.2. Notation: Quotes `like this' are ordinary textual quotation marks. Other uses of quotation marks are input to the shell. @@ -41,6 +41,7 @@ Chapter 2: How does zsh differ from...? 2.5. bash? 2.6. Shouldn't zsh be more/less like ksh/(t)csh? 2.7. What is zsh's support for Unicode/UTF-8? +2.8. Why does my bash script report an error when I run it under zsh? Chapter 3: How to get various things to work 3.1. Why does `$var' where `var="foo bar"' not do what I expect? @@ -94,6 +95,7 @@ Chapter 6: The future of zsh 6.2. Where do I report bugs, get more info / who's working on zsh? 6.3. What's on the wish-list? 6.4. Did zsh have problems in the year 2000? +6.5. When reporting a bug, how do I reduce my `.zshrc' into a minimal reproduction recipe? Acknowledgments @@ -110,17 +112,17 @@ Chapter 1: Introducing zsh and how to install it Information on zsh is available via the World Wide Web. The URL - is http://zsh.sourceforge.net/ . + is https://zsh.sourceforge.io/ . The server provides this FAQ and much else and is now maintained by the zsh workers (email zsh-workers@zsh.org <zsh-workers@zsh.org>). - The FAQ is at http://zsh.sourceforge.net/FAQ/ . + The FAQ is at https://zsh.sourceforge.io/FAQ/ . The site also contains some contributed zsh scripts and functions; we are delighted to add more, or simply links to your own collection. This document was originally written in YODL, allowing it to be converted easily into various other formats. The master source file lives at - http://zsh.sourceforge.net/FAQ/zshfaq.yo and the plain text version - can be found at http://zsh.sourceforge.net/FAQ/zshfaq.txt . + https://zsh.sourceforge.io/FAQ/zshfaq.yo and the plain text version + can be found at https://zsh.sourceforge.io/FAQ/zshfaq.txt . Another useful source of information is the collection of FAQ articles posted frequently to the Usenet news groups comp.unix.questions, @@ -145,14 +147,14 @@ The latest version of this FAQ is also available directly from any I have put together a user guide to complement the manual by explaining the most useful features of zsh in a more easy to read way. This can be found at the zsh web site: - http://zsh.sourceforge.net/Guide/ + https://zsh.sourceforge.io/Guide/ (As a method of reading the following in Emacs, you can type \M-2 \C-x $ to make all the indented text vanish, then \M-0 \C-x $ when you are on the title you want.) For any more eclectic information, you should contact the mailing - list: see question 5.2. + list: see question 6.2. 1.2: What is it? @@ -168,7 +170,7 @@ Zsh is a UNIX command interpreter (shell) which of the standard It was written by Paul Falstad when a student at Princeton; however, Paul doesn't maintain it any more and enquiries should be sent to - the mailing list (see question 5.2). Zsh is distributed under a + the mailing list (see question 6.2). Zsh is distributed under a standard Berkeley style copyright. For more information, the files Doc/intro.txt or Doc/intro.troff @@ -235,8 +237,8 @@ There used to be separate ports for Windows and OS/2, but these If you need to change something to support a new machine, it would be appreciated if you could add any necessary preprocessor code and alter configure.in and acconfig.h to configure zsh automatically, - then send the required context diffs to the list (see question - 5.2). Please make sure you have the latest version first. + then send the required unified diffs to the list (see question + 6.2). Please make sure you have the latest version first. To get it to work, retrieve the source distribution (see question 1.6), un-gzip it, un-tar it and read the INSTALL file in the top @@ -252,7 +254,7 @@ To get it to work, retrieve the source distribution (see question 1.5: What's the latest version? -Zsh 5.8.1 is the latest production version. For details of all the +Zsh 5.9 is the latest production version. For details of all the changes, see the NEWS file in the source distribution. A beta of the next version is sometimes available. Development of zsh is @@ -265,11 +267,11 @@ A beta of the next version is sometimes available. Development of zsh is development subdirectory. Note also that as the shell changes, it may become incompatible with - older versions; see the end of question 5.1 for a partial list. + older versions; see the end of question 6.1 for a partial list. Changes of this kind are almost always forced by an awkward or unnecessary feature in the original design (as perceived by current users), or to enhance compatibility with other Bourne shell - derivatives, or (mostly in the 3.0 series) to provide POSIX compliancy. + derivatives, or (mostly in the 3.0 series) to provide POSIX compliance. 1.6: Where do I get it? @@ -279,7 +281,7 @@ Note also that as the shell changes, it may become incompatible with The coordinator of development is currently me; the alias coordinator@zsh.org <coordinator@zsh.org> can be used to contact whoever is in the hot seat. https://www.zsh.org/ is the official - archive site, currently in Australia. Test versions are kept in the + archive site. Test versions are kept in the `testing' subdirectory: such up-to-the-minute development versions should only be retrieved if you actually plan to help test the latest version of the shell. @@ -304,7 +306,7 @@ Starting from mid-October 1997, there is an archive of patches sent 1.1) at: - http://zsh.sourceforge.net/Patches/ + https://zsh.sourceforge.io/Patches/ @@ -652,7 +654,8 @@ Here is Bart Schaefer's guide to converting csh aliases for zsh. 1. ) If the csh alias references "parameters" (\!:1, \!* etc.), then in zsh you need a function (referencing $1, $* etc.). - Otherwise, you can use a zsh alias. + In recent versions of zsh this can be done by defining an anonymous + function within the alias. Otherwise, a simple zsh alias suffices. 2. ) If you use a zsh function, you need to refer _at_least_ to $* in the body (inside the { }). Parameters don't magically @@ -696,7 +699,7 @@ Those first four are all you really need, but here are four more for parameters. (E.g., in a csh alias, a reference to \!:5 will cause an error if 4 or fewer arguments are given; in a zsh function, $5 is the empty string if there are 4 or fewer - parameters.) + parameters. Force an error in this example by using ${5?}.) 7. ) To begin a zsh alias with a - (dash, hyphen) character, use `alias --': @@ -717,9 +720,8 @@ There is one other serious problem with aliases: consider `l' in the function definition is in command position and is expanded as an alias, defining `/bin/ls' and `-F' as functions which call - `/bin/ls', which gets a bit recursive. This can be avoided if you use - `function' to define a function, which doesn't expand aliases. It is - possible to argue for extra warnings somewhere in this mess. + `/bin/ls', which gets a bit recursive. Recent versions of zsh treat + this as an error, but older versions silently create the functions. One workaround for this is to use the "function" keyword instead: @@ -805,11 +807,12 @@ If you're missing the editor function run-fg-editor, try something 2.5: Similarities with bash + The Bourne-Again Shell, bash, is another enhanced Bourne-like shell; the most obvious difference from zsh is that it does not attempt to emulate the Korn shell. Since both shells are under active development it is probably not sensible to be too specific here. - Broadly, bash has paid more attention to standards compliancy + Broadly, bash has paid more attention to standards compliance (i.e. POSIX) for longer, and has so far avoided the more abstruse interactive features (programmable completion, etc.) that zsh has. @@ -875,6 +878,68 @@ However, the 4.3 branch has much better support, and furthermore this fully below, see `Multibyte input and output'. +2.8: Why does my bash script report an error when I run it under zsh? + + + +tl;dr: bash is not the reference implementation of zsh, and zsh is not + a bug-for-bug compatible reimplementation of bash. + +bash and zsh are different programming languages. They are not + interchangeable; programs written for either of these languages will, + in general, not run under the other. (The situation is similar with + many other pairs of closely-related languages, such as Python 2 and + Python 3; C and C++; and even C89 and C11.) + +When bash and zsh behave differently on the same input, whether zsh's + behaviour is a bug does not depend on what bash does on the same + input; rather, it depends on what zsh's user manual specifies. + (By way of comparison, it's not a bug in Emacs that `:q!' doesn't + cause it to exit.) + +That being said, the bash and zsh languages do have a common subset, and it is + feasible to write non-trivial pieces of code that would run under either of + them, if one is sufficiently familiar with both of them. However, + a difference between bash's behaviour and zsh's does not imply that + zsh has a bug. The difference might be a bug in zsh, a bug in bash, or + a bug in neither shell + (see 3.1 for an example). + +The recommended way to deal with these differences depends on what kind + of piece of code is in question: a _script_ or a _plugin_. + +For scripts -- external commands that + are located in $PATH, or located elsewhere and are executed by + giving their path explicitly (as in `ls', `/etc/rc.d/sshd', + and `./configure') -- the answer is simple: + +Don't run bash scripts under zsh. If the scripts were written for + bash, run them in bash. There's absolutely no problem with having + `#!/usr/bin/env bash' scripts even if `zsh' is your shell for + interactive sessions. + +In fact, if you've recently changed to zsh, we _recommend_ that + you keep your scripts as `#!/usr/bin/env bash', at least for + a while: this would make the change more gradual and flatten your + learning curve. Once you're used to zsh, you can decide for each + script whether to port it to zsh or keep it as-is. + +For _plugins_ -- pieces of code + executed within the shell itself, loaded via the `.', + `source', or `autoload' builtins, added to `.zshrc', or + pasted interactively at the shell prompt -- one may consider it + worthwhile to invest the effort to make them runnable under either shell. + However, as mentioned above, doing so requires one to be familiar with both + shells, and either steer clear of their differences or handle them explicitly + with conditional code (such as `if test -n "$ZSH_VERSION"'). + +In summary, + if you'd like to run a bash script or plugin under zsh, you must port the script or plugin + properly, reviewing it line by line for differences between the two + languages and adjusting it accordingly, just like you would + when translating a book from American English to British English. + + Chapter 3: How to get various things to work @@ -910,9 +975,9 @@ For example, defining the function args to show the number of its Unless you need strict sh/ksh compatibility, you should ask yourself whether you really want this behaviour, as it can produce unexpected effects for variables with entirely innocuous embedded spaces. This - can cause horrendous quoting problems when invoking scripts from - other shells. The natural way to produce word-splitting behaviour - in zsh is via arrays. For example, + can cause horrendous quoting problems when invoking scripts written + for other shells (see 2.8). The natural way to produce + word-splitting behaviour in zsh is via arrays. For example, set -A array one two three twenty @@ -930,7 +995,7 @@ Unless you need strict sh/ksh compatibility, you should ask yourself been automatic word splitting in scalars, which is a sort of uncontrollable poor man's array. -Note that this happens regardless of the value of the internal field +Note that word splitting happens regardless of the value of the internal field separator, $IFS; in other words, with `IFS=:; foo=a:b; args $foo' you get the answer 1. @@ -962,22 +1027,32 @@ SH_WORD_SPLIT is set when zsh is invoked with the names `ksh' or `sh', or (entirely equivalent) when `emulate ksh' or `emulate sh' is in effect. -There is one other effect of word splitting which differs between ksh +There used to be another effect of word splitting which differed between ksh and zsh. In ksh, the builtin commands that declare parameters such as typeset and export force word-splitting not to take place after on an assignment argument: typeset param=`echo foo bar` - in ksh will create a parameter with value `foo bar', but in zsh will + in ksh will create a parameter with value `foo bar'. + +zsh used to create a parameter param with value foo and a parameter bar - whose value is empty. Contrast this with a normal assignment (no + whose value was empty. Contrast this with a normal assignment (no typeset or other command in front), which never causes a word split - unless you have GLOB_ASSIGN set. From zsh version 4.0.2 the option - KSH_TYPESET, set automatically in compatibility mode, fixes this - problem. Note that in bash this behaviour occurs with all arguments that - look like assignments, whatever the command name; to get this behaviour - in zsh you have to set the option MAGIC_EQUAL_SUBST. + unless you have GLOB_ASSIGN set. + +zsh version 4.0.2 and newer creates a single parameter with value + `foo bar', like ksh does, when the option KSH_TYPESET is set. + This option gets set automatically when in ksh compatibility mode. + +zsh 5.1 and newer create a single parameter with value `foo bar' by + default, in both compatibility and native modes. The older behaviour + can be obtained with `disable -r typeset'. + +If the options `MAGIC_EQUAL_SUBST' and `KSH_TYPESET' are both + set, arguments that look like assignments will not undergo word + splitting, whatever the command name. 3.2: In which startup file do I put...? @@ -2435,11 +2510,6 @@ The shell is being maintained by various (entirely self-appointed) you want someone to mail you directly, say so. Most patches to zsh appear there first. -Note that this location has just changed (January 1999), and the - instructions to go with it are slightly different --- in particular, - if you are already subscribed, the instructions about how to - unsubscribe are different. - Please note when reporting bugs that many exist only on certain architectures, which the developers may not have access to. In this case debugging information, as detailed as possible, is @@ -2457,6 +2527,11 @@ Two progressively lower volume lists exist, one with messages (posting to the last one is currently restricted). +Finally, there is a private mailing list (the general public cannot subscribe + to it) for discussing bug reports with security implications, i.e., potential + vulnerabilities: `zsh-security@zsh.org'. If you find a security problem + in zsh itself, please mail this address. + Note that you should only join one of these lists: people on zsh-workers receive all the lists, and people on zsh-users will also receive the announcements list. @@ -2470,16 +2545,18 @@ To join zsh-workers, send email to zsh-workers-subscribe@zsh.org (the actual content is unimportant). Replace subscribe with - unsubscribe to unsubscribe. The mailing software (ezlm) has + unsubscribe to unsubscribe. The mailing software (Sympa) has various bells and whistles: you can retrieve archived messages. - Mail zsh-workers-help@zsh.org <zsh-workers-help@zsh.org> for detailed information. + Mail sympa@zsh.org?subject=help <sympa@zsh.org?subject=help> for detailed information. Administrative matters are best sent to zsh-workers-owner@zsh.org <zsh-workers-owner@zsh.org>. - real name is Geoff Wing <gcw@zsh.org> <Geoff Wing <gcw@zsh.org>>. + +Note that this location changed in August 2020, and the + instructions to go with it are slightly different. An archive of mailings for the last few years can be found at http://www.zsh.org/mla/ - at the main zsh archive in Australia. + at the main zsh archive site. Of course, you can also post zsh queries to the Usenet group comp.unix.shell; if all else fails, you could even e-mail me. @@ -2519,6 +2596,92 @@ Not that I heard of; it's up to you to be careful with two-digit dates, show problems here. +6.5: When reporting a bug, how do I reduce my `.zshrc' into a minimal reproduction recipe? + + +When reporting a bug, the gold standard is to include with the bug + a _minimal reproduction recipe_, with which anyone who reads the bug + report can reproduce the bug for themselves + at will. + +When you run into a bug in the shell, particularly during interactive + use, a reproduction recipe would ideally start by running zsh -f + and then, within that instance of the shell, run a minimal short + sequence of commands that reproduces the bug. A good way to devise + such recipes is the following: + + + 1. ) First, ensure the bug is reproducible. To do this, start + a new instance of the shell -- for example, open a new tab in + your terminal emulator -- and reproduce the bug there. + +2. ) Start a new instance of the shell by running the + command `zsh -f' from your regular shell prompt, and reproduce the + bug there. (The `-f' flag inhibits `.zshenv', + `/etc/zprofile', `.zprofile', `/etc/zshrc', and + `.zshrc' from being sourced.) + +If you succeeded in reproducing the bug in `zsh -f', copy the + commands you used and their outputs (from the `zsh -f' invocation + to the point the bug occurred) and include them in your bug report. + Skip the remaining steps of this procedure. + +If, however, the bug happens in your regular shell but not in `zsh + -f', read the next steps. + +3. ) Make a backup of your .zshrc file. + +4. ) Delete your .zshrc file, start a new instance of zsh, and confirm + that the problem does not reproduce there. (If the problem + does reproduce there, it's caused by something in `.zshenv', + `.zprofile', `/etc/zprofile', or `/etc/zshrc', so apply + this procedure from the top to those files rather than to your + `.zshrc'.) + + + +5. ) At this point, you know that the problem is caused by + something in your `.zshrc' file, but not what line exactly. + To find the responsible line, we will use + a variation + of the binary search + algorithm, as follows: + +Suppose your `.zshrc' file has 200 lines. To start, copy + the first half of your `.zshrc' -- that is, lines + 1 through 100 -- from the backup copy to your live `.zshrc' + file, and check whether the bug reproduces then. Now, empty the live + `.zshrc' file again, and copy the second half of your + `.zshrc' file from the backup to the live `.zshrc' file + -- the live file should now contain lines 101 through 200, only + -- and see whether the problem reproduces. + +Normally, the bug will reproduce either with lines 1 through 100 + or with lines 101 through 200, but not in both cases. To isolate + the specific line that causes the bug, repeat the above process on the + relevant half of the file: for example, if you've determined that the + bug reproduces when only lines 101 through 200 are installed, check + whether the bug reproduces (a) when only lines 101 through 150 are + installed, and (b) when only lines 151 through 200 are installed. + Repeat the process until the resulting `.zshrc' is minimal. + +It is not important to break the file into two halves exactly. + Breaking the file into two parts sized one-third and two-thirds, for + example, will work equally well. You can even try restoring one line + at a time, but this is impractical for all but the shortest + `.zshrc' files. + +6. ) Include the minimal set of lines you devised in the previous + step, along with the commands you used and their outputs, in your bug + report. + +7. ) Restore your `.zshrc' from backup. + + +Bug reports should be emailed to the `zsh-workers@zsh.org' public + mailing list; see 6.2 for details. + + Acknowledgments: @@ -2536,7 +2699,7 @@ Copyright Information: This document is copyright (C) P.W. Stephenson, 1995, 1996, 1997, -1998, 1999, 2000, 2012. This text originates in the U.K. and the author +1998, 1999, 2000, 2012, 2020. This text originates in the U.K. and the author asserts his moral rights under the Copyrights, Designs and Patents Act, 1988. @@ -2547,4 +2710,4 @@ notice appears in all copies of this documentation. Remember, however, that this document changes monthly and it may be more useful to provide a pointer to it rather than the entire text. A suitable pointer is "information on the Z-shell can be obtained on the World -Wide Web at URL http://zsh.sourceforge.net/". +Wide Web at URL https://zsh.sourceforge.io/". |