migration from bash

This is based on the man page included with Mac Os Montery 12.6 10/17/22. Official versions should be be viewed at zsh.org
As with all the documentation found on this website this is tersified.
Since this is a migration document the reader is expeceted to be familiar with bash.

The manual is a number of sections:

roadmap Informal introduction to the manual
misc Anything not fitting into the other sections
expn command and parameter expansion
param parameters
options options
builtins built-in functions
zle command line editing
compwid completion widgets
compsys completion system
compctl completion control
modules loadable modules
tcpsys built-in TCP functions
zftpsys built-in FTP client
contrib Additional functions and utilities
all Meta-man page containing all of the above

Command interpreter (shell) usable as an interactive login shell and as a shell script command processor. Of the common shells, resembles ksh with many enhancements. It does not provide compatibility with POSIX or other shells by default.

Includes command line editing, spelling correction, programmable command completion, shell functions (with autoloading), a history mechanism.

-i interactive. a script is permitted
-c first argument is a command , rather than reading commands from a script or standard input.
Second argument is assigned to $0.
-s read commands from the standard input. Without -s argument is a script

Without -c or -s remaining arguments, after option processing, the first argument is a script

After the first one or two arguments , the remaining arguments are assigned to the positional parameters.

see zshoptions.

Option specifying

To use options by name use -o name []
For example:
 zsh -o shwordsplit scr 
runs the script scr with SH_WORD_SPLIT.

Options are turned off using +o.

o can suffix single-letter options. Examples: `-xo shwordsplit' or `-xoshwordsplit' is equivalent to `-x -o shwordsplit'.

Options may be specified by name in long style --option-name. When this is done, `-'s in the option name are translated into `_' and ignored.
for example, `zsh --sh-word-split' invokes zsh with SH_WORD_SPLIT .
Options are turned off with a `+'; thus `+-sh-word-split' is equivalent to `--no-sh-word-split'.

Long options cannot be suffixes.

--version sends version information to standard output
--help sends a list of options that can be used when invoking the shell to standard output

To allow an argument to begin with a -, option processing is terminated with a lone - , + , -- , +- or stacked with preceeding options (-x- is equivalent to -x --) .
`-b' or `+b' ends option processing. `-b' is like `--', except that further single-letter options can be stacked after the `-b'


Emulates sh or ksh when invoked as sh or ksh.
Invoked as su uses the name from $SHELL and emulation is based on that.

The --emulate, as a first option, followed by an emulation mode may be passed to the shell. The emulation modes are those described for the emulate builtin, see zshbuiltins.

Subsequent options may modify the requested emulation mode. Extra steps are taken to ensure a smooth emulation when this option is used compared with emulate within the shell: for example, variables that conflict with POSIX usage such as path are not defined within the shell.

In sh and ksh compatibility modes ARGC, argv, cdpath, fignore, fpath, HISTCHARS, mailpath, MANPATH, manpath, path, prompt, PROMPT, PROMPT2, PROMPT3, PROMPT4, psvar, status, watch are not special and not initialized.

The zsh startup/shutdown scripts are not executed.

Login shells source /etc/profile, $HOME/.profile. If $ENV is set on invocation, it is sourced after the profile scripts.
The value of ENV is subjected to parameter expansion, command substitution, and arithmetic expansion before being interpreted as a pathname. PRIVILEGED affects the execution of startup files.


invoked as sh BSD_ECHO and IGNORE_BRACES are set


builtin commands NOT in bash

autoload [ {+|-}UXktz ] [ -w ] [ name]

Equivalent to functions -u, with the exception of -X/+X and -w.
-X may be used only inside a shell function, and may not be followed by a name, causes the calling function to be marked for autoloading and then immediately loaded and executed, with the current array of positional parameters as arguments. This replaces the previous definition of the function.
If no function definition is found, an error is printed and the function remains undefined and marked for autoloading.
+X loads each name as an autoloaded function, but does not execute it.
The exit status is zero (success) if the function was not previously defined and a definition for it was found.
This does not replace any existing definition of the function.
The exit status is nonzero (failure) if the function was already defined or when no definition was found. In the latter case the function remains undefined and marked for autoloading.
If ksh-style autoloading is enabled, the function created will contain the contents of the file plus a call to the function itself appended to it, giving normal ksh autoloading behaviour on the first call to the function.

With -w files are compiled with zcompile builtin and functions defined in them are marked for autoloading.

-z and -k mark the function to be autoloaded in native or ksh emulation, as if KSH_AUTOLOAD were unset or were set, respectively. The flags override the setting of the option at the time the function is loaded.


If $ZDOTDIR is unset $HOME is used .

At startup

  1. /etc/zshenv Commands are read, this cannot be overridden.
    It is run for all instances of zsh, and should be as small as possible. code that does not need to be run for every shell should be behind a test of the form if [[ -o rcs ]]; then … so that it will not be executed when zsh is invoked with -f.
    RCS (set by default) if unset supresses processing of subsequent startup files.
    GLOBAL_RCS (set by default) if unset supresses processing of subsequent global startup files (those shown here with an path starting with a /).
    A file in $ZDOTDIR can re-enable GLOBAL_RCS.

  2. $ZDOTDIR/.zshenv
  3. /etc/zprofile
  4. $ZDOTDIR/.zprofile if the shell is a login shell,
  5. $ZDOTDIR/.zshrc if interactive.
  6. /etc/zlogin
  7. $ZDOTDIR/.zlogin if the shell is a login shell,

When the login shell exits:

  1. $ZDOTDIR/.zlogout
  2. /etc/zlogout are processed unless the shell terminates due to exec'ing another process
These are affected by $RCS and $GLOBAL_RCS .
If $RCS is unset no history file will be saved.

Compiled files newer than the original will be used (see zshbuiltins zcompile).


       ${TMPPREFIX}*   (default is /tmp/zsh*)
       /etc/zlogout    (installation-specific - /etc is the default)

SEE ALSO sh(1), csh(1), tcsh(1), rc(1), bash(1), ksh(1), zshall(1), zshbuiltins(1), zshcompwid(1), zshcompsys(1), zshcompctl(1), zshcontrib(1), zshexpn(1), zshmisc(1), zshmodules(1), zshoptions(1), zshparam(1), zshroadmap(1), zshtcpsys(1), zshzftpsys(1), zshzle(1)

A user guide is at http://zsh.sourceforge.net/Guide/. At

Apple does things a little differently .