path: root/README

-----------------
THE Z SHELL (ZSH)
-----------------

Version
-------

This is version 4.3.14 of the shell.  This is a development release,
but is believed to be reasonably stable.  Sites where the users need to
edit command lines with multibyte characters (in particular UTF-8)
will probably want to upgrade.  The previous widely released version
of the shell was 4.3.12.

Installing Zsh
--------------

The instructions for compiling zsh are in the file INSTALL.  You should
also check the file MACHINES in the top directory to see if there
are any special instructions for your particular architecture.

Note in particular the zsh/newuser module that guides new users through
setting basic shell options without the administrator's intervention.  This
is turned on by default.  See the section AUTOMATIC NEW USER CONFIGURATION
in INSTALL for configuration information.

Features
--------

Zsh is a shell with lots of features.  For a list of some of these, see the
file FEATURES, and for the latest changes see NEWS.  For more
details, see the documentation.

Possible incompatibilities
---------------------------

In some 4.3.X releases of zsh, the completion system added a ".."  as a
trial completion whenever completing directories.  This was a bug: as
documented in the zshcompsys manual, this feature needs to be turned on by
a style:

  zstyle ':completion:*' special-dirs true


The rest of this section documents incompatibilities in the shell since the
4.2 series of releases.

In previous releases of the shell, builtin commands and precommand
modifiers that did not accept options also did not recognize the
argument "--" as marking the end of option processing without being
considered an argument.  This was not documented and was incompatible
with other shells.  All such commands now handle this syntax.

The configuration option --enable-lfs to enable large file support has
been replaced by autoconf's standard --enable-largefile mechanism.
As this is usually used whenever necessary, this won't usually
be noticeable; however, anyone configuring with --disable-lfs
should configure with --disable-largefile instead.

The configuration option --with-curses-terminfo has been replaced
by the option --with-term-lib="LIBS" where LIBS is a space-separated
list of libraries to search for termcap and curses features.

The option SH_WORD_SPLIT, used in Bourne/Korn/Posix shell compatibility
mode, has been made more like other shells in the case of substitutions of
the form ${1+"$@"} (a common trick used to work around problems in older
Bourne shells) or any of the related forms with the + replaced by - or =
with an optional colon preceding.  Previously, with SH_WORD_SPLIT in
effect, this expression would cause splitting on all white space in the
shell arguments.  (This was always regarded as a bug but was long-standing
behaviour.)  Now it is treated identically to "$@".  The same change
applies to expressions with forced splitting such as ${=1+"$@"}, but
otherwise the case where SH_WORD_SPLIT is not set is unaffected.

Debug traps (`trap ... DEBUG' or the function TRAPDEBUG) now run by default
before the command to which they refer instead of after.  This is almost
always the right behaviour for the intended purpose of debugging and is
consistent with recent versions of other shells.  The option
DEBUG_BEFORE_CMD can be unset to revert to the previous behaviour.

Previously, process substitutions of the form =(...), <(...) and >(...)
were only handled if they appeared as separate command arguments.
(However, the latter two forms caused the current argument to be
terminated and a new one started even if they occurred in the middle of
a string.)  Now all three may be followed by other strings, and the
latter two may also be preceded by other strings.  Remaining
limitations on their use (to reduce incompatibilities to a minimum)
are documented in the zshexpn.1 manual.

In previous versions of the shell it was possible to use index 0 in an
array or string subscript to refer to the same element as index 1 if the
option KSH_ARRAYS was not in effect.  This was a limited approximation to
the full KSH_ARRAYS handling and so was not very useful.  In this version
of the shell, this behaviour is only provided when the option
KSH_ZERO_SUBSCRIPT is set.  Note that despite the name this does not provide
true compatibility with ksh or other shells and KSH_ARRAYS should still be
used for that purpose.  By default, the option is not set; an array
subscript that evaluates to 0 returns an empty string or array element and
attempts to write to an array or string range including only a zero
subscript are treated as an error.  Writes to otherwise valid ranges that
also include index zero are allowed; hence for example the assignment
  array[(R)notfound,(r)notfound]=()
(where the string "notfound" does not match an element in $array) sets the
entire array to be empty, as in previous versions of the shell.
KSH_ZERO_SUBSCRIPT is irrelevant when KSH_ARRAYS is set.  Also as in previous
versions, attempts to write to non-existent elements at the end of an array
cause the array to be suitably extended.  This difference means that, for
example
  array[(R)notfound]=(replacement)
is an error if KSH_ZERO_SUBSCRIPT is not set (new behaviour), while
  array[(r)notfound]=(replacement)
causes the given value to be appended to the array (same behaviour as
previous versions).

The "exec" precommand modifier now takes various options for compatibility
with other shells.  This means that whereas "exec -prog" previously
tried to execute a command name "-prog", it will now report an error
in option handling.  "exec -- -prog" will execute "-prog".  If
the option EQUALS is set, as it is by default in zsh's native mode,
"exec =-prog" behaves the same way in all versions of zsh provided
the command can be found.

The "unset" builtin now does not regard the unsetting of non-existent
variables as an error, so can still return status 0 (depending on the
handling of other arguments).  This appears to be the standard shell
behaviour.

The variable BAUD is no longer set automatically by the shell.
In previous versions it was set to the baud rate reported by
the terminal driver in order to initialise the line editor's
compensation mechanism for slow baud rates.  However, the baud
rate so reported is very rarely related to the limiting speed of
screen updates on modern systems.  Users who need the compensation
mechanism should set BAUD to an appropriate rate by hand.

The variable HOME is no longer set by the shell if zsh is emulating any
other shell at startup; it must be present in the environment or set
subsequently by the user.  It is valid for the variable to be unset.

If the shell starts in a mode where it is emulating another shell
(typically because the base name of the shell was "sh" or another known
shell), the "repeat" syntax is not available by default, to avoid clashes
with external commands, but the "ulimit" command is available by default.
"limit", "sched" and "unlimit" are not available by default in such modes:
this has been the case for many versions but is now documented for the
first time.  (Users should note that emulation modes are not designed for
backwards compatibility with previous versions of zsh, but to maximise
compatibility with other shells, hence it is not safe to assume emulation
modes will behave consistently between zsh versions.)

Parameter substitutions in the form ${param//#%search/replace} match
against "search" anchored at both ends of the parameter value.  Previously
this syntax would have matched against "%search", anchored only at the head
of the value.  The form ${param//#$search/replace} where the value
$search starts with "%" considers the "%" to be part of the search
string as before.

Configure attempts to decide if multibyte characters are supported by the
system and if so sets the effect of --enable-multibyte, unless
--disable-multibyte was passed on the command line.  When
--enable-multibyte is in effect, the MULTIBYTE shell option is on by
default; this causes many operations to recognise characters in the current
locale.  (Most typically this is used for a UTF-8 character set but the
shell will work with any character set provided by the system where
individual octets are either US ASCII characters or have the top bit set.)
Older versions of the shell always assumed a character was one byte; this
remains the case if --disable-multibyte is in effect or if the MULTIBYTE
option is unset.  In some places the width of characters will be taken into
account where previously a raw string length was used; this is transparent
in calculations of screen position, but also occurs, for example, in
calculations of padding width.  Note that MULTIBYTE is not automatically
set when emulating Bourne- and POSIX-style shells; for interactive use of
these emulations it may be necessary to set it by hand.  Note also that the
option COMBINING_CHARS is not set by default due to difficulties detecting
the ability of the terminal to display combining characters correctly; MAC
users in particular will probably wish to set this option.

Zsh has previously been lax about whether it allows octets with the
top bit set to be part of a shell identifier.  Older versions of the shell
assumed all such octets were allowed in identifiers, however the POSIX
standard does not allow such characters in identifiers.  The older
behaviour is still obtained with --disable-multibyte in effect.
With --enable-multibyte in effect (see previous paragraph) there are three
possible cases:
  MULTIBYTE option unset:  only ASCII characters are allowed; the
    shell does not attempt to identify non-ASCII characters at all.
  MULTIBYTE option set, POSIX_IDENTIFIERS option unset: in addition
    to the POSIX characters, any alphanumeric characters in the
    local character set are allowed.  Note that scripts and functions that
    take advantage of this are non-portable; however, this is in the spirit
    of previous versions of the shell.  Note also that the options must
    be set before the shell parses the script or function; setting
    them during execution is not sufficient.
  MULITBYTE option set, POSIX_IDENTIFIERS set:  only ASCII characters
    are allowed in identifiers even though the shell will recognise
    alphanumeric multibyte characters.

The sched builtin now keeps entries in time order.  This means that
after adding an entry the index of an existing entry used for deletion
may change, if that entry had a later time than the new entry.  However,
deleting a entry with a later time will now never change the index of an
entry with an earlier time, which could happen with the previous method.

The completion style pine-directory must now be set to use completion
for PINE mailbox folders; previously it had the default ~/mail.  This
change was necessary because otherwise recursive directories under
~/mail were searched by default, which could be a considerable unnecessary
hit for anyone not using PINE.  The previous default can be restored with:
  zstyle ':completion:*' pine-directory ~/mail

The completion style fake-files now allows patterns as directories,
for example the value '/home/*:.snapshot' is now valid.  This will
only cause problems in the unlikely event that a directory in the style
has a pattern character in it.

The default maximum function depth (configurable with
--enable-max-function-depth) has been decreased to 1000 from 4096.  The
previous value was observed to be small enough that crashes still occurred
on some fairly common PC configurations.  This change is only likely to
affect some highly specialised uses of the shell.

The variables HISTCHARS and histchars now reject any attempt to
set non-ASCII characters for history or comments.  Multibyte characters
have never worked and the most consistent change was to restrict the
set to portable characters only.

Writers of add-on modules should note that the API has changed
significantly to allow user control of individual features provided by
modules.  See the documentation for zmodload -F and
Etc/zsh-development-guide, in that order.

Documentation
-------------

There are a number of documents about zsh in this distribution:

Doc/Zsh/*.yo	The master source for the zsh documentation is written in
		yodl.  Yodl is a document language written by Karel Kubat.
		It is not required by zsh but it is a nice program so you
		might want to get it anyway, especially if you are a zsh
		developer.  It can be downloaded from
		ftp://yodl.sourceforge.net/

Doc/zsh*.1	Man pages in nroff format.  These will be installed
		by "make install.man" or "make install".  By default,
		these will be installed in /usr/local/man/man1, although
		you can change this with the --mandir option to configure
		or editing the user configuration section of the top level
		Makefile.

Doc/zsh.texi	Everything the man pages have, but in texinfo format.  These
		will be installed by "make install.info" or "make install".
		By default, these will be installed in /usr/local/info,
		although you can change this with the --infodir option to
		configure or editing the user configuration section of the
		top level Makefile.  Version 4.0 or above of the
		Texinfo tools are recommended for processing this file.

Also included in the distribution are:

Doc/intro.ms	An introduction to zsh in troff format using the ms
		macros.  This document explains many of the features
		that make zsh more equal than other shells.
		Unfortunately this is based on zsh-2.5 so some examples
		may not work without changes but it is still a good
		introduction.

For more information, see the website, as described in the META-FAQ.

If you do not have the necessary tools to process these documents, PDF,
Info and DVI versions are available in the separate file zsh-doc.tar.gz at
the archive sites listed in the META-FAQ.

The distribution also contains a Perl script in Utils/helpfiles which
can be used to extract the descriptions of builtin commands from the
zshbuiltins manual page.  See the comments at the beginning of the
script about its usage.  The files created by this script can be used
by example function run-help located in the subdirectory Functions/Misc to
show information about zsh builtins and run `man' on external commands.
For this the shell variable HELPDIR should point to a directory containing
the files generated by the helpfiles script.  run-help should be
unaliased before loading the run-help function.  After that this function
will be executed by the run-help ZLE function which is by default bound
to ESC-h in emacs mode.

Examples
--------

Examples of zsh startup files are located in the subdirectory
StartupFiles.  Examples of zsh functions and scripts are located in
the subdirectory Functions.  Examples of completion control commands
(compctl) are located in the file Misc/compctl-examples.

Zsh FTP Sites, Web Pages, and Mailing Lists
-------------------------------------------

The current list of zsh FTP sites, web pages, and mailing lists can be
found in the META-FAQ.  A copy is included in this distribution and is
available separately at any of the zsh FTP sites.

Common Problems and Frequently Asked Questions
----------------------------------------------

Zsh has a list of Frequently Asked Questions (FAQ) maintained by Peter
Stephenson <pws@zsh.org>.  It covers many common problems encountered
when building, installing, and using zsh.  A copy is included in this
distribution in Etc/FAQ and is available separately at any of the zsh
ftp sites.

Zsh Maintenance and Bug Reports
-------------------------------

Zsh is currently maintained by the members of the zsh-workers mailing list
and coordinated by Peter Stephenson <coordinator@zsh.org>.  Please send
any feedback and bugs reports to <zsh-workers@zsh.org>.

Reports are most helpful if you can reproduce the bug starting zsh with
the -f option.  This skips the execution of local startup files except
/etc/zshenv.  If a bug occurs only when some options set try to locate
the option which triggers the bug.

There is a script "reporter" in the subdirectory Util which will print out
your current shell environment/setup.  If you cannot reproduce the bug
with "zsh -f", use this script and include the output from sourcing this
file.  This way, the problem you are reporting can be recreated.

The known bugs in zsh are listed in the file Etc/BUGS.  Check this as
well as the Frequently Asked Questions (FAQ) list before sending a bug
report.  Note that zsh has some features which are not compatible with
sh but these are not bugs.  Most of these incompatibilities go away
when zsh is invoked as sh or ksh (e.g. using a symbolic link).

If you send a bug report to the list and are not a subscriber, please
mention this in your message if you want a response.

If you would like to contribute to the development and maintenance of zsh,
then you should join the zsh-workers mailing list (check the META-FAQ
for info on this).  You should also read the "zsh-development-guide"
located in the subdirectory Util.

Contributors
------------

The people who have contributed to this software project are listed
in Etc/CONTRIBUTORS.