Bugs tend to be tracked on the zsh-workers mailing list; see the next section. Check the mailing list to see if a bug has been reported. (There is a bug tracker at the zsh development site at Sourceforge, but it's not in active use.)
To see how recent versions of the shell have changed, look at the README file in the source distribution. This indicates the most important changes, and in particular draws attention to incompatibilities you might notice.
The shell is being maintained by various (entirely self-appointed) subscribers to the mailing list,
zsh-workers@zsh.org
so mail on any issues (bug reports, suggestions, complaints...)
related to the development of the shell should be sent there. If
you want someone to mail you directly, say so. Most patches to zsh
appear there first.
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 particularly welcome.
Two progressively lower volume lists exist, one with messages concerning the use of zsh,
zsh-users@zsh.org
and one just containing announcements: about releases, about major
changes in the shell, or this FAQ, for example,
zsh-announce@zsh.org
(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.
The lists are handled by an automated server. The instructions for zsh-announce and zsh-users are the same as for zsh-workers: just change zsh-workers to whatever in the following.
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 (Sympa) has
various bells and whistles: you can retrieve archived messages.
Mail sympa@zsh.org?subject=help for detailed information.
Administrative matters are best sent to
zsh-workers-owner@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 site.
The code bears the marks of the ages and many things could be done much better with a rewrite. A more efficient set of code for lexing/parsing/execution might also be an advantage. Volunteers are particularly welcome for these tasks.
Some future possibilities which have been suggested:
Not that I heard of; it's up to you to be careful with two-digit dates,
though, which are produced by the prompt escapes %W and %D,
and also by the command `print -P'. Earlier versions of zsh may
show problems here.
.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:
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.
.zshrc file.
.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.)
.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.
.zshrc from backup.
Bug reports should be emailed to the zsh-workers@zsh.org public
mailing list; see 6.2 for details.
Thanks to zsh-list, in particular Bart Schaefer, for suggestions regarding this document. Zsh has been in the hands of archivists Jim Mattson, Bas de Bakker, Richard Coleman, Zoltan Hidvegi and Andrew Main, and the mailing list has been run by Peter Gray, Rick Ohnemus, Richard Coleman, Karsten Thygesen and Geoff Wing, all of whom deserve thanks. The world is eternally in the debt of Paul Falstad for inventing zsh in the first place (though the wizzo extended completion is by Sven Wischnowsky).
This document is copyright (C) P.W. Stephenson, 1995, 1996, 1997, 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.
Permission is hereby granted, without written agreement and without license or royalty fees, to use, copy, modify, and distribute this documentation for any purpose, provided that the above copyright 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 https://zsh.sourceforge.io/".