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 SourceForge/zsh
As with all the documentation found on this website this is tersified.
This is a migration document the reader is expeceted to be familiar with bash and Mac OS.

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 ( Not in Mac version )
contrib Additional functions and utilities
all Meta-man page containing all of the above

Command interpreter (shell) zsh is usable as an interactive login shell and as a shell script command processor. Of the common shells, zsh 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.

To set the default shel use chsh -s /bin/bash

-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.


In that document: options that are set by default in all emulations are marked <D>efault; those set by default only are marked <C>sh, <K>sh, <S>h, <Z>sh . Listing options: (with setopt, unsetopt, set -o or set +o), 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.

Command history

With bash using vi esc k rettrieves the last command. And additional k retrieves the previous …. esc / searches the history for the text folling the slash.

Using zsh …


For non-interactive shells, or interactive shells with interactive_comments set, a word beginning with histchars[3](orgin 1!) (default # ) begins a comment which continues until the end-of-line .

With extended_glob (default set)
#   matchs zero or more of the pattern (corresponds to the regular expression modifier *)
## matchs one or more                          (corresponds to the regular expression modifier +).
If used intending to be a comment, zsh reports bad pattern!

Examples of treatment of #:

$ setopt extended_glob
$ echo hello # hello : hello  --- a history pattern match
zsh: bad pattern: #

$ unsetopt extended_glob
$ echo hello # hello : hello --- a regular character
hello # hello : hello

$ setopt interactive_comments
$ echo hello # hello : hello    --- a comment for the rest of the line.

$ histchars[3]=:                --- changing  to use : as comment leading.
$ echo hello # hello : hello
hello # hello

bash interactive_comments  on by default in interactive shells.

$ echo hello # hello
$ shopt -u interactive_comments   unset it
$ echo hello # hello
hello # hello

if [ -e .vimrc    bash true if .vimrc exists, zsh ...
if [ -a .vimrc    bash true if .vimrc exists, zsh [: too many arguments
if [ -d /Volume/DATA    bash true if /Volume/DATA exists, zsh false

$x == 0   #  expected logical test to return result
zsh: = not found

$x=';'   # expected x to be assigned string value of ;
zsh: ; not found

$x="x"  # expected x to be assigned string value of  x
     .zprofile is executed !

When encounters:
set   editing-mode vi 
zsh reports  zsh:1: command not found: editing-mode

set |g vi
'*'=( editing-mode vi )
@=( editing-mode vi )
argv=( editing-mode vi )


'!'=0           also  echo $! reports  0
'*'=( editing-mode vi )
@=( editing-mode vi )

                                    1/14/22 227 files since Dec 28, increasing in size fo 40KB to 100kb !
SHELL_SESSION_HISTFILE_NEW=/Users/$USER/.zsh_sessions/C75FC5F8-92F5-4886-92D7-F2FB6FC7516D.historynew    0 created at login(?)
The first two histchars (default ! ^ ) are used in history expansions.

--emulate mode can be used as the first option.
modes are described for the emulate builtin, see

When is compared with the emulate command : variables that conflict with POSIX usage such as path are not defined.

In sh and ksh compatibility modes :

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.

    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 for a login shell, $ZDOTDIR/.zshrc for interactive.
  5. /etc/zlogin
  6. $ZDOTDIR/.zlogin for 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