1ZSHOPTIONS(1)               General Commands Manual              ZSHOPTIONS(1)
2
3
4

NAME

6       zshoptions - zsh options
7

SPECIFYING OPTIONS

9       Options are primarily referred to by name.  These names are case insen‐
10       sitive and underscores are ignored.  For example, `allexport' is equiv‐
11       alent to `A__lleXP_ort'.
12
13       The  sense of an option name may be inverted by preceding it with `no',
14       so `setopt No_Beep' is equivalent to `unsetopt beep'.   This  inversion
15       can only be done once, so `nonobeep' is not a synonym for `beep'.  Sim‐
16       ilarly, `tify' is not  a  synonym  for  `nonotify'  (the  inversion  of
17       `notify').
18
19       Some  options also have one or more single letter names.  There are two
20       sets of single letter options: one used by default, and another used to
21       emulate  sh/ksh  (used  when the SH_OPTION_LETTERS option is set).  The
22       single letter options can be used on the shell command  line,  or  with
23       the  set, setopt and unsetopt builtins, as normal Unix options preceded
24       by `-'.
25
26       The sense of the single letter options may be  inverted  by  using  `+'
27       instead  of  `-'.   Some  of the single letter option names refer to an
28       option being off, in which case the inversion of that  name  refers  to
29       the  option  being  on.  For example, `+n' is the short name of `exec',
30       and `-n' is the short name of its inversion, `noexec'.
31
32       In strings of single letter options supplied to the shell  at  startup,
33       trailing  whitespace  will  be ignored; for example the string `-f    '
34       will be treated just as `-f', but the string `-f i' is an error.   This
35       is  because many systems which implement the `#!' mechanism for calling
36       scripts do not strip trailing whitespace.
37

DESCRIPTION OF OPTIONS

39       In the following list, options set by default  in  all  emulations  are
40       marked  <D>;  those  set by default only in csh, ksh, sh, or zsh emula‐
41       tions are marked <C>, <K>,  <S>,  <Z>  as  appropriate.   When  listing
42       options  (by  `setopt', `unsetopt', `set -o' or `set +o'), those turned
43       on by default appear in the list prefixed  with  `no'.   Hence  (unless
44       KSH_OPTION_PRINT is set), `setopt' shows all options whose settings are
45       changed from the default.
46
47   Changing Directories
48       AUTO_CD (-J)
49              If a command is issued that can't be executed as a  normal  com‐
50              mand, and the command is the name of a directory, perform the cd
51              command to that directory.  This option is  only  applicable  if
52              the  option  SHIN_STDIN  is set, i.e. if commands are being read
53              from standard input.  The option  is  designed  for  interactive
54              use;  it is recommended that cd be used explicitly in scripts to
55              avoid ambiguity.
56
57       AUTO_PUSHD (-N)
58              Make cd push the old directory onto the directory stack.
59
60       CDABLE_VARS (-T)
61              If the argument to a cd command  (or  an  implied  cd  with  the
62              AUTO_CD  option set) is not a directory, and does not begin with
63              a slash, try to expand the expression as if it were preceded  by
64              a `~' (see the section `Filename Expansion').
65
66       CHASE_DOTS
67              When  changing  to  a  directory  containing a path segment `..'
68              which would otherwise be treated as canceling the previous  seg‐
69              ment in the path (in other words, `foo/..' would be removed from
70              the path, or if `..' is the first part of  the  path,  the  last
71              part of the current working directory would be removed), instead
72              resolve the path to the  physical  directory.   This  option  is
73              overridden by CHASE_LINKS.
74
75              For  example,  suppose  /foo/bar  is  a  link  to  the directory
76              /alt/rod.  Without this option set, `cd /foo/bar/..' changes  to
77              /foo;  with it set, it changes to /alt.  The same applies if the
78              current directory is /foo/bar and `cd ..' is  used.   Note  that
79              all other symbolic links in the path will also be resolved.
80
81       CHASE_LINKS (-w)
82              Resolve symbolic links to their true values when changing direc‐
83              tory.  This also has the effect of CHASE_DOTS, i.e. a `..'  path
84              segment  will  be  treated  as referring to the physical parent,
85              even if the preceding path segment is a symbolic link.
86
87       POSIX_CD <K> <S>
88              Modifies the behaviour of cd, chdir and pushd commands  to  make
89              them more compatible with the POSIX standard. The behaviour with
90              the option unset is described in the documentation  for  the  cd
91              builtin in zshbuiltins(1).  If the option is set, the shell does
92              not test for directories beneath the local directory (`.') until
93              after all directories in cdpath have been tested.
94
95              Also, if the option is set, the conditions under which the shell
96              prints the new directory after changing to it are modified.   It
97              is no longer restricted to interactive shells (although printing
98              of the directory stack with pushd is still limited  to  interac‐
99              tive  shells); and any use of a component of CDPATH, including a
100              `.' but excluding an empty component that is  otherwise  treated
101              as `.', causes the directory to be printed.
102
103       PUSHD_IGNORE_DUPS
104              Don't push multiple copies of the same directory onto the direc‐
105              tory stack.
106
107       PUSHD_MINUS
108              Exchanges the meanings of `+' and `-' when used with a number to
109              specify a directory in the stack.
110
111       PUSHD_SILENT (-E)
112              Do not print the directory stack after pushd or popd.
113
114       PUSHD_TO_HOME (-D)
115              Have pushd with no arguments act like `pushd $HOME'.
116
117   Completion
118       ALWAYS_LAST_PROMPT <D>
119              If  unset,  key functions that list completions try to return to
120              the last prompt if given a numeric argument. If set these  func‐
121              tions try to return to the last prompt if given no numeric argu‐
122              ment.
123
124       ALWAYS_TO_END
125              If a completion is performed with the cursor within a word,  and
126              a full completion is inserted, the cursor is moved to the end of
127              the word.  That is, the cursor is moved to the end of  the  word
128              if  either a single match is inserted or menu completion is per‐
129              formed.
130
131       AUTO_LIST (-9) <D>
132              Automatically list choices on an ambiguous completion.
133
134       AUTO_MENU <D>
135              Automatically use menu completion after the  second  consecutive
136              request  for  completion,  for  example  by pressing the tab key
137              repeatedly. This option is overridden by MENU_COMPLETE.
138
139       AUTO_NAME_DIRS
140              Any parameter that is set to the absolute name  of  a  directory
141              immediately becomes a name for that directory, that will be used
142              by the `%~' and related prompt sequences, and will be  available
143              when completion is performed on a word starting with `~'.  (Oth‐
144              erwise, the parameter must be used in the form `~param' first.)
145
146       AUTO_PARAM_KEYS <D>
147              If a parameter name was  completed  and  a  following  character
148              (normally  a space) automatically inserted, and the next charac‐
149              ter typed is one of those that have to come directly  after  the
150              name (like `}', `:', etc.), the automatically added character is
151              deleted, so that the character typed comes immediately after the
152              parameter  name.   Completion  in  a brace expansion is affected
153              similarly: the added character is a `,', which will  be  removed
154              if `}' is typed next.
155
156       AUTO_PARAM_SLASH <D>
157              If  a  parameter  is  completed  whose  content is the name of a
158              directory, then add a trailing slash instead of a space.
159
160       AUTO_REMOVE_SLASH <D>
161              When the last character resulting from a completion is  a  slash
162              and  the next character typed is a word delimiter, a slash, or a
163              character that ends a command (such as a semicolon or an  amper‐
164              sand), remove the slash.
165
166       BASH_AUTO_LIST
167              On  an ambiguous completion, automatically list choices when the
168              completion function is called twice in succession.   This  takes
169              precedence  over  AUTO_LIST.   The  setting of LIST_AMBIGUOUS is
170              respected.  If AUTO_MENU is set, the menu  behaviour  will  then
171              start  with  the third press.  Note that this will not work with
172              MENU_COMPLETE, since repeated completion calls immediately cycle
173              through the list in that case.
174
175       COMPLETE_ALIASES
176              Prevents  aliases on the command line from being internally sub‐
177              stituted before completion is attempted.  The effect is to  make
178              the alias a distinct command for completion purposes.
179
180       COMPLETE_IN_WORD
181              If unset, the cursor is set to the end of the word if completion
182              is started. Otherwise it stays there and completion is done from
183              both ends.
184
185       GLOB_COMPLETE
186              When  the current word has a glob pattern, do not insert all the
187              words resulting from the expansion but generate matches  as  for
188              completion  and  cycle  through  them  like  MENU_COMPLETE.  The
189              matches are generated as if a `*' was added to the  end  of  the
190              word,  or  inserted  at the cursor when COMPLETE_IN_WORD is set.
191              This actually uses pattern matching, not globbing, so  it  works
192              not only for files but for any completion, such as options, user
193              names, etc.
194
195              Note that when the pattern matcher  is  used,  matching  control
196              (for  example,  case-insensitive or anchored matching) cannot be
197              used.  This limitation only applies when the current  word  con‐
198              tains a pattern; simply turning on the GLOB_COMPLETE option does
199              not have this effect.
200
201       HASH_LIST_ALL <D>
202              Whenever  a  command  completion  or  spelling   correction   is
203              attempted,  make  sure  the entire command path is hashed first.
204              This makes the first completion slower but avoids false  reports
205              of spelling errors.
206
207       LIST_AMBIGUOUS <D>
208              This  option works when AUTO_LIST or BASH_AUTO_LIST is also set.
209              If there is an unambiguous prefix to insert on the command line,
210              that is done without a completion list being displayed; in other
211              words, auto-listing behaviour  only  takes  place  when  nothing
212              would  be  inserted.   In the case of BASH_AUTO_LIST, this means
213              that the list will be delayed to the third call of the function.
214
215       LIST_BEEP <D>
216              Beep on an ambiguous completion.  More accurately,  this  forces
217              the  completion  widgets to return status 1 on an ambiguous com‐
218              pletion, which causes the shell to beep if the  option  BEEP  is
219              also  set;  this  may be modified if completion is called from a
220              user-defined widget.
221
222       LIST_PACKED
223              Try to make the completion list smaller (occupying  less  lines)
224              by printing the matches in columns with different widths.
225
226       LIST_ROWS_FIRST
227              Lay  out  the  matches  in completion lists sorted horizontally,
228              that is, the second match is to the right of the first one,  not
229              under it as usual.
230
231       LIST_TYPES (-X) <D>
232              When  listing files that are possible completions, show the type
233              of each file with a trailing identifying mark.
234
235       MENU_COMPLETE (-Y)
236              On an ambiguous completion, instead of listing possibilities  or
237              beeping,  insert the first match immediately.  Then when comple‐
238              tion is requested again, remove the first match and  insert  the
239              second  match,  etc.  When there are no more matches, go back to
240              the first one again.  reverse-menu-complete may be used to  loop
241              through  the  list in the other direction. This option overrides
242              AUTO_MENU.
243
244       REC_EXACT (-S)
245              If the string on the command line exactly  matches  one  of  the
246              possible  completions,  it is accepted, even if there is another
247              completion (i.e. that string with  something  else  added)  that
248              also matches.
249
250   Expansion and Globbing
251       BAD_PATTERN (+2) <C> <Z>
252              If  a  pattern for filename generation is badly formed, print an
253              error message.  (If this option is unset, the  pattern  will  be
254              left unchanged.)
255
256       BARE_GLOB_QUAL <Z>
257              In  a  glob  pattern,  treat  a trailing set of parentheses as a
258              qualifier list, if it contains no `|', `(' or (if  special)  `~'
259              characters.  See the section `Filename Generation'.
260
261       BRACE_CCL
262              Expand  expressions  in braces which would not otherwise undergo
263              brace expansion to a lexically ordered list of all  the  charac‐
264              ters.  See the section `Brace Expansion'.
265
266       CASE_GLOB <D>
267              Make  globbing  (filename  generation)  sensitive to case.  Note
268              that other uses of patterns are always sensitive  to  case.   If
269              the option is unset, the presence of any character which is spe‐
270              cial to filename generation will cause  case-insensitive  match‐
271              ing.   For  example, cvs(/) can match the directory CVS owing to
272              the  presence  of  the  globbing   flag   (unless   the   option
273              BARE_GLOB_QUAL is unset).
274
275       CASE_MATCH <D>
276              Make  regular  expressions using the zsh/regex module (including
277              matches with =~) sensitive to case.
278
279       CSH_NULL_GLOB <C>
280              If a pattern for filename generation has no matches, delete  the
281              pattern  from  the  argument list; do not report an error unless
282              all the patterns  in  a  command  have  no  matches.   Overrides
283              NOMATCH.
284
285       EQUALS <Z>
286              Perform = filename expansion.  (See the section `Filename Expan‐
287              sion'.)
288
289       EXTENDED_GLOB
290              Treat the `#', `~' and `^' characters as part  of  patterns  for
291              filename  generation, etc.  (An initial unquoted `~' always pro‐
292              duces named directory expansion.)
293
294       FORCE_FLOAT
295              Constants in arithmetic evaluation will be treated  as  floating
296              point  even  without  the  use of a decimal point; the values of
297              integer variables will be converted to floating point when  used
298              in  arithmetic  expressions.   Integers in any base will be con‐
299              verted.
300
301       GLOB (+F, ksh: +f) <D>
302              Perform filename generation (globbing).  (See the section `File‐
303              name Generation'.)
304
305       GLOB_ASSIGN <C>
306              If  this  option  is set, filename generation (globbing) is per‐
307              formed on the right hand side of scalar parameter assignments of
308              the  form  `name=pattern (e.g. `foo=*').  If the result has more
309              than one word the parameter will  become  an  array  with  those
310              words  as  arguments. This option is provided for backwards com‐
311              patibility only: globbing is always performed on the right  hand
312              side  of  array  assignments  of  the  form `name=(value)' (e.g.
313              `foo=(*)') and this form is recommended for clarity;  with  this
314              option  set,  it  is  not possible to predict whether the result
315              will be an array or a scalar.
316
317       GLOB_DOTS (-4)
318              Do not require a leading `.' in a filename to be matched explic‐
319              itly.
320
321       GLOB_STAR_SHORT
322              When this option is set and the default zsh-style globbing is in
323              effect, the pattern `**/*' can be abbreviated to  `**'  and  the
324              pattern `***/*' can be abbreviated to ***.  Hence `**.c' finds a
325              file ending in .c in any subdirectory, and `***.c' does the same
326              while  also following symbolic links.  A / immediately after the
327              `**' or `***' forces the pattern to be treated as the unabbrevi‐
328              ated form.
329
330       GLOB_SUBST <C> <K> <S>
331              Treat any characters resulting from parameter expansion as being
332              eligible for filename expansion and filename generation, and any
333              characters resulting from command substitution as being eligible
334              for filename generation.  Braces (and commas in between) do  not
335              become eligible for expansion.
336
337       HIST_SUBST_PATTERN
338              Substitutions  using  the  :s  and :& history modifiers are per‐
339              formed with pattern matching instead of string  matching.   This
340              occurs  wherever  history  modifiers  are  valid, including glob
341              qualifiers and parameters.  See the section  Modifiers  in  zsh‐
342              expn(1).
343
344       IGNORE_BRACES (-I) <S>
345              Do  not  perform  brace  expansion.  For historical reasons this
346              also includes the effect of the IGNORE_CLOSE_BRACES option.
347
348       IGNORE_CLOSE_BRACES
349              When neither this option nor IGNORE_BRACES is set, a sole  close
350              brace character `}' is syntactically significant at any point on
351              a command line.  This has the effect that no semicolon  or  new‐
352              line  is  necessary  before  the brace terminating a function or
353              current shell construct.  When either option is set,  a  closing
354              brace  is  syntactically  significant  only in command position.
355              Unlike IGNORE_BRACES, this option does not disable brace  expan‐
356              sion.
357
358              For  example,  with both options unset a function may be defined
359              in the following fashion:
360
361                     args() { echo $# }
362
363              while if either option is set, this does not work and  something
364              equivalent to the following is required:
365
366                     args() { echo $#; }
367
368       KSH_GLOB <K>
369              In  pattern  matching,  the  interpretation  of  parentheses  is
370              affected by a preceding `@', `*', `+', `?' or `!'.  See the sec‐
371              tion `Filename Generation'.
372
373       MAGIC_EQUAL_SUBST
374              All unquoted arguments of the form `anything=expression' appear‐
375              ing after the command name have  filename  expansion  (that  is,
376              where  expression has a leading `~' or `=') performed on expres‐
377              sion as if it were a parameter assignment.  The argument is  not
378              otherwise  treated  specially;  it is passed to the command as a
379              single argument, and not used as an actual parameter assignment.
380              For  example,  in  echo  foo=~/bar:~/rod,  both occurrences of ~
381              would be replaced.  Note that this happens anyway  with  typeset
382              and similar statements.
383
384              This  option respects the setting of the KSH_TYPESET option.  In
385              other words, if both options are in  effect,  arguments  looking
386              like assignments will not undergo word splitting.
387
388       MARK_DIRS (-8, ksh: -X)
389              Append  a  trailing  `/'  to  all directory names resulting from
390              filename generation (globbing).
391
392       MULTIBYTE <D>
393              Respect multibyte characters when found in strings.   When  this
394              option  is set, strings are examined using the system library to
395              determine how many bytes form a character, depending on the cur‐
396              rent  locale.   This  affects  the way characters are counted in
397              pattern matching, parameter values and various delimiters.
398
399              The option is on by default  if  the  shell  was  compiled  with
400              MULTIBYTE_SUPPORT;  otherwise  it  is  off by default and has no
401              effect if turned on.
402
403              If the option is off a single byte is always treated as a single
404              character.   This  setting  is  designed  purely  for  examining
405              strings known to contain raw bytes or other values that may  not
406              be  characters  in  the  current locale.  It is not necessary to
407              unset the option merely because the character set for  the  cur‐
408              rent locale does not contain multibyte characters.
409
410              The  option  does  not  affect the shell's editor,  which always
411              uses the locale to  determine  multibyte  characters.   This  is
412              because  the character set displayed by the terminal emulator is
413              independent of shell settings.
414
415       NOMATCH (+3) <C> <Z>
416              If a pattern for filename generation has no  matches,  print  an
417              error,  instead  of  leaving  it unchanged in the argument list.
418              This also applies to file expansion of an initial `~' or `='.
419
420       NULL_GLOB (-G)
421              If a pattern for filename generation has no matches, delete  the
422              pattern  from  the  argument list instead of reporting an error.
423              Overrides NOMATCH.
424
425       NUMERIC_GLOB_SORT
426              If numeric filenames are matched by a filename  generation  pat‐
427              tern,  sort  the filenames numerically rather than lexicographi‐
428              cally.
429
430       RC_EXPAND_PARAM (-P)
431              Array expansions of the form `foo${xx}bar', where the  parameter
432              xx  is  set  to  (a  b c), are substituted with `fooabar foobbar
433              foocbar' instead of the default `fooa b  cbar'.   Note  that  an
434              empty array will therefore cause all arguments to be removed.
435
436       REMATCH_PCRE
437              If  set,  regular  expression matching with the =~ operator will
438              use Perl-Compatible Regular Expressions from the  PCRE  library.
439              (The  zsh/pcre  module  must be available.)  If not set, regular
440              expressions will use the extended regexp syntax provided by  the
441              system libraries.
442
443       SH_GLOB <K> <S>
444              Disables  the special meaning of `(', `|', `)' and '<' for glob‐
445              bing the result of parameter and command substitutions,  and  in
446              some  other places where the shell accepts patterns.  If SH_GLOB
447              is set but KSH_GLOB is not, the shell allows the  interpretation
448              of  subshell  expressions  enclosed in parentheses in some cases
449              where there is no space before  the  opening  parenthesis,  e.g.
450              !(true)  is  interpreted  as  if there were a space after the !.
451              This option is set by default if zsh is invoked as sh or ksh.
452
453       UNSET (+u, ksh: +u) <K> <S> <Z>
454              Treat unset parameters as if they were empty when  substituting.
455              Otherwise they are treated as an error.
456
457       WARN_CREATE_GLOBAL
458              Print  a warning message when a global parameter is created in a
459              function by an assignment or in math context.  This often  indi‐
460              cates  that  a  parameter  has  not  been declared local when it
461              should have been.  Parameters explicitly  declared  global  from
462              within a function using typeset -g do not cause a warning.  Note
463              that there is no warning when a local parameter is  assigned  to
464              in a nested function, which may also indicate an error.
465
466       WARN_NESTED_VAR
467              Print  a  warning  message  when  an  existing parameter from an
468              enclosing function scope, or global, is set in a function by  an
469              assignment  or  in  math  context.   Assignment to shell special
470              parameters does not cause a warning.  This is the  companion  to
471              WARN_CREATE_GLOBAL  as  in this case the warning is only printed
472              when a parameter is not created.  Where possible, use of typeset
473              -g to set the parameter suppresses the error, but note that this
474              needs to be used every time the parameter is set.   To  restrict
475              the effect of this option to a single function scope, use `func‐
476              tions -W'.
477
478              For example, the following  code  produces  a  warning  for  the
479              assignment  inside  the  function  nested  as that overrides the
480              value within toplevel
481
482                     toplevel() {
483                       local foo="in fn"
484                       nested
485                     }
486                     nested() {
487                          foo="in nested"
488                     }
489                     setopt warn_nested_var
490                     toplevel
491
492   History
493       APPEND_HISTORY <D>
494              If this is set, zsh sessions will append their history  list  to
495              the  history file, rather than replace it. Thus, multiple paral‐
496              lel zsh sessions will all have the new entries from  their  his‐
497              tory  lists  added  to  the history file, in the order that they
498              exit.  The file will still be periodically re-written to trim it
499              when the number of lines grows 20% beyond the value specified by
500              $SAVEHIST (see also the HIST_SAVE_BY_COPY option).
501
502       BANG_HIST (+K) <C> <Z>
503              Perform textual history expansion, csh-style, treating the char‐
504              acter `!' specially.
505
506       EXTENDED_HISTORY <C>
507              Save  each  command's  beginning timestamp (in seconds since the
508              epoch) and the duration (in seconds) to the history  file.   The
509              format of this prefixed data is:
510
511              `: <beginning time>:<elapsed seconds>;<command>'.
512
513       HIST_ALLOW_CLOBBER
514              Add `|' to output redirections in the history.  This allows his‐
515              tory references to clobber files even when CLOBBER is unset.
516
517       HIST_BEEP <D>
518              Beep in ZLE when a widget attempts to  access  a  history  entry
519              which isn't there.
520
521       HIST_EXPIRE_DUPS_FIRST
522              If  the  internal history needs to be trimmed to add the current
523              command line, setting this option will cause the oldest  history
524              event  that  has  a  duplicate to be lost before losing a unique
525              event from the list.  You should be sure to  set  the  value  of
526              HISTSIZE  to  a larger number than SAVEHIST in order to give you
527              some room for the duplicated events, otherwise this option  will
528              behave  just like HIST_IGNORE_ALL_DUPS once the history fills up
529              with unique events.
530
531       HIST_FCNTL_LOCK
532              When writing out the history file, by default  zsh  uses  ad-hoc
533              file  locking to avoid known problems with locking on some oper‐
534              ating systems.  With this option locking is done by means of the
535              system's  fcntl call, where this method is available.  On recent
536              operating systems this may provide better performance,  in  par‐
537              ticular  avoiding  history  corruption  when files are stored on
538              NFS.
539
540       HIST_FIND_NO_DUPS
541              When searching for history entries in the line  editor,  do  not
542              display  duplicates  of  a  line  previously  found, even if the
543              duplicates are not contiguous.
544
545       HIST_IGNORE_ALL_DUPS
546              If a new command line being added to the history list duplicates
547              an  older  one, the older command is removed from the list (even
548              if it is not the previous event).
549
550       HIST_IGNORE_DUPS (-h)
551              Do not enter command lines into the history  list  if  they  are
552              duplicates of the previous event.
553
554       HIST_IGNORE_SPACE (-g)
555              Remove  command lines from the history list when the first char‐
556              acter on the line is a  space,  or  when  one  of  the  expanded
557              aliases  contains  a  leading  space.   Only normal aliases (not
558              global or suffix aliases) have this behaviour.   Note  that  the
559              command  lingers  in the internal history until the next command
560              is entered before it vanishes, allowing you to briefly reuse  or
561              edit the line.  If you want to make it vanish right away without
562              entering another command, type a space and press return.
563
564       HIST_LEX_WORDS
565              By default, shell history that is read in from  files  is  split
566              into  words  on all white space.  This means that arguments with
567              quoted whitespace are not correctly  handled,  with  the  conse‐
568              quence  that references to words in history lines that have been
569              read from a file may be inaccurate.  When this  option  is  set,
570              words  read  in  from a history file are divided up in a similar
571              fashion to normal shell command line  handling.   Although  this
572              produces  more  accurately  delimited  words, if the size of the
573              history file is large this can be slow.  Trial and error is nec‐
574              essary to decide.
575
576       HIST_NO_FUNCTIONS
577              Remove  function  definitions  from the history list.  Note that
578              the function lingers in the internal history until the next com‐
579              mand  is entered before it vanishes, allowing you to briefly re‐
580              use or edit the definition.
581
582       HIST_NO_STORE
583              Remove the history (fc -l) command from the  history  list  when
584              invoked.   Note that the command lingers in the internal history
585              until the next command is entered before it  vanishes,  allowing
586              you to briefly reuse or edit the line.
587
588       HIST_REDUCE_BLANKS
589              Remove  superfluous blanks from each command line being added to
590              the history list.
591
592       HIST_SAVE_BY_COPY <D>
593              When the history file is re-written, we  normally  write  out  a
594              copy of the file named $HISTFILE.new and then rename it over the
595              old one.  However, if this option is unset, we instead  truncate
596              the old history file and write out the new version in-place.  If
597              one of the history-appending options  is  enabled,  this  option
598              only  has  an  effect when the enlarged history file needs to be
599              re-written to trim it down to size.  Disable this  only  if  you
600              have  special  needs, as doing so makes it possible to lose his‐
601              tory entries if zsh gets interrupted during the save.
602
603              When writing out a copy of the history file, zsh  preserves  the
604              old file's permissions and group information, but will refuse to
605              write out a new file if  it  would  change  the  history  file's
606              owner.
607
608       HIST_SAVE_NO_DUPS
609              When writing out the history file, older commands that duplicate
610              newer ones are omitted.
611
612       HIST_VERIFY
613              Whenever the user enters a line with  history  expansion,  don't
614              execute  the  line  directly; instead, perform history expansion
615              and reload the line into the editing buffer.
616
617       INC_APPEND_HISTORY
618              This option works like APPEND_HISTORY except  that  new  history
619              lines  are added to the $HISTFILE incrementally (as soon as they
620              are entered), rather than waiting until the  shell  exits.   The
621              file  will  still be periodically re-written to trim it when the
622              number of lines grows 20% beyond the value specified  by  $SAVE‐
623              HIST (see also the HIST_SAVE_BY_COPY option).
624
625       INC_APPEND_HISTORY_TIME
626              This  option  is a variant of INC_APPEND_HISTORY in which, where
627              possible, the history entry is written out to the file after the
628              command  is  finished,  so that the time taken by the command is
629              recorded correctly in the history file in EXTENDED_HISTORY  for‐
630              mat.   This  means  that the history entry will not be available
631              immediately from other instances of the shell that are using the
632              same history file.
633
634              This  option is only useful if INC_APPEND_HISTORY and SHARE_HIS‐
635              TORY are turned off.  The three  options  should  be  considered
636              mutually exclusive.
637
638       SHARE_HISTORY <K>
639
640              This option both imports new commands from the history file, and
641              also causes your typed commands to be appended  to  the  history
642              file  (the  latter  is like specifying INC_APPEND_HISTORY, which
643              should be turned off if this option is in effect).  The  history
644              lines  are  also  output  with  timestamps  ala EXTENDED_HISTORY
645              (which makes it easier to find the spot where we left off  read‐
646              ing the file after it gets re-written).
647
648              By  default,  history movement commands visit the imported lines
649              as well as the local lines, but you can toggle this on  and  off
650              with  the set-local-history zle binding.  It is also possible to
651              create a zle widget that will make some commands ignore imported
652              commands, and some include them.
653
654              If  you  find  that you want more control over when commands get
655              imported,   you   may   wish   to   turn   SHARE_HISTORY    off,
656              INC_APPEND_HISTORY  or  INC_APPEND_HISTORY_TIME  (see above) on,
657              and then manually import commands whenever you need  them  using
658              `fc -RI'.
659
660   Initialisation
661       ALL_EXPORT (-a, ksh: -a)
662              All parameters subsequently defined are automatically exported.
663
664       GLOBAL_EXPORT <Z>
665              If  this  option  is  set,  passing  the -x flag to the builtins
666              declare, float, integer, readonly and typeset  (but  not  local)
667              will  also  set  the  -g flag;  hence parameters exported to the
668              environment will not be made local to  the  enclosing  function,
669              unless they were already or the flag +g is given explicitly.  If
670              the option is unset, exported parameters will be made  local  in
671              just the same way as any other parameter.
672
673              This  option is set by default for backward compatibility; it is
674              not recommended that its behaviour be relied  upon.   Note  that
675              the  builtin  export  always  sets both the -x and -g flags, and
676              hence its effect extends beyond the scope of the enclosing func‐
677              tion; this is the most portable way to achieve this behaviour.
678
679       GLOBAL_RCS (-d) <D>
680              If  this  option  is  unset,  the  startup  files /etc/zprofile,
681              /etc/zshrc, /etc/zlogin and /etc/zlogout will not  be  run.   It
682              can  be  disabled  and  re-enabled at any time, including inside
683              local startup files (.zshrc, etc.).
684
685       RCS (+f) <D>
686              After /etc/zshenv is sourced on  startup,  source  the  .zshenv,
687              /etc/zprofile, .zprofile, /etc/zshrc, .zshrc, /etc/zlogin, .zlo‐
688              gin, and .zlogout files, as described in  the  section  `Files'.
689              If  this option is unset, the /etc/zshenv file is still sourced,
690              but any of the others will not be; it can be set at any time  to
691              prevent  the remaining startup files after the currently execut‐
692              ing one from being sourced.
693
694   Input/Output
695       ALIASES <D>
696              Expand aliases.
697
698       CLOBBER (+C, ksh: +C) <D>
699              Allows `>' redirection to truncate  existing  files.   Otherwise
700              `>!' or `>|' must be used to truncate a file.
701
702              If  the  option is not set, and the option APPEND_CREATE is also
703              not set, `>>!' or `>>|' must be  used  to  create  a  file.   If
704              either option is set, `>>' may be used.
705
706       CORRECT (-0)
707              Try  to  correct  the spelling of commands.  Note that, when the
708              HASH_LIST_ALL option is not set or when some directories in  the
709              path  are  not readable, this may falsely report spelling errors
710              the first time some commands are used.
711
712              The shell variable CORRECT_IGNORE may be set  to  a  pattern  to
713              match words that will never be offered as corrections.
714
715       CORRECT_ALL (-O)
716              Try to correct the spelling of all arguments in a line.
717
718              The  shell  variable CORRECT_IGNORE_FILE may be set to a pattern
719              to match file names that will never be offered as corrections.
720
721       DVORAK Use the Dvorak keyboard instead of the standard qwerty  keyboard
722              as  a  basis for examining spelling mistakes for the CORRECT and
723              CORRECT_ALL options and the spell-word editor command.
724
725       FLOW_CONTROL <D>
726              If this option is unset,  output  flow  control  via  start/stop
727              characters  (usually  assigned  to  ^S/^Q)  is  disabled  in the
728              shell's editor.
729
730       IGNORE_EOF (-7)
731              Do not exit on end-of-file.  Require the use of exit  or  logout
732              instead.   However, ten consecutive EOFs will cause the shell to
733              exit anyway, to avoid the shell hanging if its tty goes away.
734
735              Also, if this option is set and the Zsh  Line  Editor  is  used,
736              widgets implemented by shell functions can be bound to EOF (nor‐
737              mally Control-D) without printing the  normal  warning  message.
738              This works only for normal widgets, not for completion widgets.
739
740       INTERACTIVE_COMMENTS (-k) <K> <S>
741              Allow comments even in interactive shells.
742
743       HASH_CMDS <D>
744              Note the location of each command the first time it is executed.
745              Subsequent invocations of the same command will  use  the  saved
746              location,  avoiding  a path search.  If this option is unset, no
747              path hashing is done at all.  However, when CORRECT is set, com‐
748              mands whose names do not appear in the functions or aliases hash
749              tables are hashed in order to avoid reporting them  as  spelling
750              errors.
751
752       HASH_DIRS <D>
753              Whenever a command name is hashed, hash the directory containing
754              it, as well as all directories that occur earlier in  the  path.
755              Has no effect if neither HASH_CMDS nor CORRECT is set.
756
757       HASH_EXECUTABLES_ONLY
758              When  hashing commands because of HASH_CMDS, check that the file
759              to be hashed is actually an executable.  This option is unset by
760              default  as  if the path contains a large number of commands, or
761              consists of many remote files, the additional tests can  take  a
762              long  time.  Trial and error is needed to show if this option is
763              beneficial.
764
765       MAIL_WARNING (-U)
766              Print a warning message if a mail file has been  accessed  since
767              the shell last checked.
768
769       PATH_DIRS (-Q)
770              Perform  a  path  search  even  on command names with slashes in
771              them.  Thus if `/usr/local/bin' is in the user's path, and he or
772              she  types  `X11/xinit',  the command `/usr/local/bin/X11/xinit'
773              will be executed  (assuming  it  exists).   Commands  explicitly
774              beginning  with  `/',  `./' or `../' are not subject to the path
775              search.  This also applies to the `.' and source builtins.
776
777              Note that subdirectories of the  current  directory  are  always
778              searched  for  executables  specified  in this form.  This takes
779              place before any search indicated by this option, and regardless
780              of  whether  `.'  or the current directory appear in the command
781              search path.
782
783       PATH_SCRIPT <K> <S>
784              If this option  is  not  set,  a  script  passed  as  the  first
785              non-option  argument  to  the shell must contain the name of the
786              file to open.  If this option is set, and the  script  does  not
787              specify  a directory path, the script is looked for first in the
788              current directory, then in the command path.   See  the  section
789              INVOCATION in zsh(1).
790
791       PRINT_EIGHT_BIT
792              Print  eight  bit characters literally in completion lists, etc.
793              This option is not necessary if your  system  correctly  returns
794              the printability of eight bit characters (see ctype(3)).
795
796       PRINT_EXIT_VALUE (-1)
797              Print  the  exit  value  of  programs with non-zero exit status.
798              This is only  available  at  the  command  line  in  interactive
799              shells.
800
801       RC_QUOTES
802              Allow  the  character  sequence  `'''  to signify a single quote
803              within singly quoted strings.   Note  this  does  not  apply  in
804              quoted strings using the format $'...', where a backslashed sin‐
805              gle quote can be used.
806
807       RM_STAR_SILENT (-H) <K> <S>
808              Do not query the user before executing `rm *' or `rm path/*'.
809
810       RM_STAR_WAIT
811              If querying the user before executing `rm  *'  or  `rm  path/*',
812              first  wait  ten seconds and ignore anything typed in that time.
813              This avoids the problem of reflexively answering  `yes'  to  the
814              query  when  one  didn't really mean it.  The wait and query can
815              always be avoided by expanding the `*' in ZLE (with tab).
816
817       SHORT_LOOPS <C> <Z>
818              Allow the short forms of for, repeat, select, if,  and  function
819              constructs.
820
821       SUN_KEYBOARD_HACK (-L)
822              If  a line ends with a backquote, and there are an odd number of
823              backquotes on the line, ignore the trailing backquote.  This  is
824              useful  on some keyboards where the return key is too small, and
825              the backquote key lies annoyingly close to it.  As  an  alterna‐
826              tive the variable KEYBOARD_HACK lets you choose the character to
827              be removed.
828
829   Job Control
830       AUTO_CONTINUE
831              With this option set, stopped jobs that are removed from the job
832              table  with  the disown builtin command are automatically sent a
833              CONT signal to make them running.
834
835       AUTO_RESUME (-W)
836              Treat single word simple commands without redirection as  candi‐
837              dates for resumption of an existing job.
838
839       BG_NICE (-6) <C> <Z>
840              Run all background jobs at a lower priority.  This option is set
841              by default.
842
843       CHECK_JOBS <Z>
844              Report the status of background and suspended jobs before  exit‐
845              ing a shell with job control; a second attempt to exit the shell
846              will succeed.  NO_CHECK_JOBS is best used  only  in  combination
847              with NO_HUP, else such jobs will be killed automatically.
848
849              The  check is omitted if the commands run from the previous com‐
850              mand line included a `jobs' command, since  it  is  assumed  the
851              user  is  aware  that there are background or suspended jobs.  A
852              `jobs' command run from one of the hook functions defined in the
853              section  SPECIAL FUNCTIONS in zshmisc(1) is not counted for this
854              purpose.
855
856       CHECK_RUNNING_JOBS <Z>
857              Check for both running and suspended  jobs  when  CHECK_JOBS  is
858              enabled.  When this option is disabled, zsh checks only for sus‐
859              pended jobs, which matches the default behavior of bash.
860
861              This option has no effect unless CHECK_JOBS is set.
862
863       HUP <Z>
864              Send the HUP signal to running jobs when the shell exits.
865
866       LONG_LIST_JOBS (-R)
867              Print job notifications in the long format by default.
868
869       MONITOR (-m, ksh: -m)
870              Allow job control.  Set by default in interactive shells.
871
872       NOTIFY (-5, ksh: -b) <Z>
873              Report the status of background jobs  immediately,  rather  than
874              waiting until just before printing a prompt.
875
876       POSIX_JOBS <K> <S>
877              This  option  makes  job  control  more compliant with the POSIX
878              standard.
879
880              When the option is not set, the MONITOR option is unset on entry
881              to subshells, so that job control is no longer active.  When the
882              option is set, the MONITOR option and job control remain  active
883              in  the  subshell,  but  note that the subshell has no access to
884              jobs in the parent shell.
885
886              When the option is not set, jobs put in the background or  fore‐
887              ground  with  bg  or  fg are displayed with the same information
888              that would be reported by jobs.  When the option  is  set,  only
889              the  text  is  printed.   The  output  from  jobs  itself is not
890              affected by the option.
891
892              When the option is not set,  job  information  from  the  parent
893              shell is saved for output within a subshell (for example, within
894              a pipeline).  When the option is set,  the  output  of  jobs  is
895              empty until a job is started within the subshell.
896
897              In  previous  versions  of the shell, it was necessary to enable
898              POSIX_JOBS in order for the builtin command wait to  return  the
899              status  of  background jobs that had already exited.  This is no
900              longer the case.
901
902   Prompting
903       PROMPT_BANG <K>
904              If set, `!' is  treated  specially  in  prompt  expansion.   See
905              EXPANSION OF PROMPT SEQUENCES in zshmisc(1).
906
907       PROMPT_CR (+V) <D>
908              Print  a  carriage  return  just before printing a prompt in the
909              line editor.  This is on by default  as  multi-line  editing  is
910              only  possible  if  the editor knows where the start of the line
911              appears.
912
913       PROMPT_SP <D>
914              Attempt to preserve a partial line (i.e. a line that did not end
915              with  a  newline) that would otherwise be covered up by the com‐
916              mand prompt due to the PROMPT_CR option.   This  works  by  out‐
917              putting  some  cursor-control  characters, including a series of
918              spaces, that should make the terminal wrap to the next line when
919              a  partial line is present (note that this is only successful if
920              your terminal has automatic margins, which is typical).
921
922              When a partial line is preserved, by default  you  will  see  an
923              inverse+bold  character  at  the end of the partial line:  a `%'
924              for a normal user or a `#' for root.  If set, the shell  parame‐
925              ter PROMPT_EOL_MARK can be used to customize how the end of par‐
926              tial lines are shown.
927
928              NOTE: if the PROMPT_CR option is not set, enabling  this  option
929              will have no effect.  This option is on by default.
930
931       PROMPT_PERCENT <C> <Z>
932              If  set,  `%'  is  treated  specially  in prompt expansion.  See
933              EXPANSION OF PROMPT SEQUENCES in zshmisc(1).
934
935       PROMPT_SUBST <K> <S>
936              If set, parameter expansion, command substitution and arithmetic
937              expansion   are  performed  in  prompts.   Substitutions  within
938              prompts do not affect the command status.
939
940       TRANSIENT_RPROMPT
941              Remove any right prompt from display when  accepting  a  command
942              line.   This  may  be useful with terminals with other cut/paste
943              methods.
944
945   Scripts and Functions
946       ALIAS_FUNC_DEF <S>
947              By default, zsh does not allow the definition of functions using
948              the  `name  ()'  syntax  if  name was expanded as an alias: this
949              causes an error.  This is usually the desired behaviour, as oth‐
950              erwise  the  combination of an alias and a function based on the
951              same definition can easily cause problems.
952
953              When this option is set, aliases can be used for defining  func‐
954              tions.
955
956              For  example,  consider  the following definitions as they might
957              occur in a startup file.
958
959                     alias foo=bar
960                     foo() {
961                       print This probably does not do what you expect.
962                     }
963
964              Here, foo is expanded as an  alias  to  bar  before  the  ()  is
965              encountered,  so  the  function  defined would be named bar.  By
966              default this is instead an error  in  native  mode.   Note  that
967              quoting  any  part  of  the  function name, or using the keyword
968              function, avoids the problem, so is recommended when  the  func‐
969              tion name can also be an alias.
970
971       C_BASES
972              Output hexadecimal numbers in the standard C format, for example
973              `0xFF' instead of the usual `16#FF'.  If the option OCTAL_ZEROES
974              is  also  set  (it  is  not  by  default), octal numbers will be
975              treated similarly and hence appear as `077' instead  of  `8#77'.
976              This  option has no effect on the choice of the output base, nor
977              on the output of bases other than hexadecimal and  octal.   Note
978              that  these  formats will be understood on input irrespective of
979              the setting of C_BASES.
980
981       C_PRECEDENCES
982              This alters the precedence of arithmetic operators  to  be  more
983              like  C  and other programming languages; the section ARITHMETIC
984              EVALUATION in zshmisc(1) has an explicit list.
985
986       DEBUG_BEFORE_CMD <D>
987              Run the DEBUG trap before each  command;  otherwise  it  is  run
988              after each command.  Setting this option mimics the behaviour of
989              ksh 93; with the option unset the behaviour is that of ksh 88.
990
991       ERR_EXIT (-e, ksh: -e)
992              If a command has a non-zero exit status, execute the ZERR  trap,
993              if set, and exit.  This is disabled while running initialization
994              scripts.
995
996              The behaviour is also disabled inside DEBUG traps.  In this case
997              the  option  is  handled  specially: it is unset on entry to the
998              trap.  If the option  DEBUG_BEFORE_CMD  is  set,  as  it  is  by
999              default,  and  the  option ERR_EXIT is found to have been set on
1000              exit, then the command for which the DEBUG trap  is  being  exe‐
1001              cuted is skipped.  The option is restored after the trap exits.
1002
1003              Non-zero status in a command list containing && or || is ignored
1004              for commands not at the end of the list.  Hence
1005
1006                     false && true
1007
1008              does not trigger exit.
1009
1010              Exiting due to ERR_EXIT has certain interactions with  asynchro‐
1011              nous jobs noted in the section JOBS in zshmisc(1).
1012
1013       ERR_RETURN
1014              If a command has a non-zero exit status, return immediately from
1015              the enclosing function.   The  logic  is  similar  to  that  for
1016              ERR_EXIT,  except  that an implicit return statement is executed
1017              instead of an exit.  This will trigger an exit at the  outermost
1018              level of a non-interactive script.
1019
1020              Normally  this  option  inherits  the behaviour of ERR_EXIT that
1021              code followed by `&&' `||' does not trigger a return.  Hence  in
1022              the following:
1023
1024                     summit || true
1025
1026              no  return  is  forced  as the combined effect always has a zero
1027              return status.
1028
1029              Note. however, that if summit in the above example is  itself  a
1030              function,  code inside it is considered separately: it may force
1031              a return from summit (assuming the  option  remains  set  within
1032              summit),  but not from the enclosing context.  This behaviour is
1033              different from ERR_EXIT which is unaffected by function scope.
1034
1035       EVAL_LINENO <Z>
1036              If set, line numbers of expressions evaluated using the  builtin
1037              eval  are tracked separately of the enclosing environment.  This
1038              applies both to the parameter LINENO and the line number  output
1039              by  the  prompt  escape  %i.   If  the option is set, the prompt
1040              escape %N will output the string `(eval)' instead of the  script
1041              or function name as an indication.   (The two prompt escapes are
1042              typically used in the parameter PS4 to be output when the option
1043              XTRACE is set.)  If EVAL_LINENO is unset, the line number of the
1044              surrounding script or function is retained  during  the  evalua‐
1045              tion.
1046
1047       EXEC (+n, ksh: +n) <D>
1048              Do execute commands.  Without this option, commands are read and
1049              checked for syntax errors, but not executed.  This option cannot
1050              be  turned off in an interactive shell, except when `-n' is sup‐
1051              plied to the shell at startup.
1052
1053       FUNCTION_ARGZERO <C> <Z>
1054              When executing a shell function or sourcing  a  script,  set  $0
1055              temporarily  to the name of the function/script.  Note that tog‐
1056              gling FUNCTION_ARGZERO from on to off (or off to  on)  does  not
1057              change  the  current  value of $0.  Only the state upon entry to
1058              the function or script has an effect.  Compare POSIX_ARGZERO.
1059
1060       LOCAL_LOOPS
1061              When this option is not set, the effect of  break  and  continue
1062              commands  may  propagate outside function scope, affecting loops
1063              in calling functions.  When the option is set in a calling func‐
1064              tion,  a  break or a continue that is not caught within a called
1065              function (regardless of the setting of the  option  within  that
1066              function) produces a warning and the effect is cancelled.
1067
1068       LOCAL_OPTIONS <K>
1069              If  this option is set at the point of return from a shell func‐
1070              tion, most options (including this one) which were in force upon
1071              entry  to  the  function  are  restored;  options  that  are not
1072              restored are PRIVILEGED and RESTRICTED.   Otherwise,  only  this
1073              option, and the LOCAL_LOOPS, XTRACE and PRINT_EXIT_VALUE options
1074              are restored.  Hence if this is  explicitly  unset  by  a  shell
1075              function  the other options in force at the point of return will
1076              remain so.  A shell function can also guarantee itself  a  known
1077              shell  configuration  with  a formulation like `emulate -L zsh';
1078              the -L activates LOCAL_OPTIONS.
1079
1080       LOCAL_PATTERNS
1081              If this option is set at the point of return from a shell  func‐
1082              tion,  the  state  of  pattern disables, as set with the builtin
1083              command `disable -p', is restored to what it was when the  func‐
1084              tion  was  entered.   The behaviour of this option is similar to
1085              the effect of LOCAL_OPTIONS on options; hence  `emulate  -L  sh'
1086              (or  indeed  any  other  emulation with the -L option) activates
1087              LOCAL_PATTERNS.
1088
1089       LOCAL_TRAPS <K>
1090              If this option is set when a signal trap is set inside  a  func‐
1091              tion,  then the previous status of the trap for that signal will
1092              be restored when the function exits.  Note that this option must
1093              be  set  prior  to  altering  the  trap behaviour in a function;
1094              unlike LOCAL_OPTIONS, the value on exit  from  the  function  is
1095              irrelevant.   However,  it  does  not  need to be set before any
1096              global trap for that to be correctly  restored  by  a  function.
1097              For example,
1098
1099                     unsetopt localtraps
1100                     trap - INT
1101                     fn() { setopt localtraps; trap '' INT; sleep 3; }
1102
1103              will restore normal handling of SIGINT after the function exits.
1104
1105       MULTI_FUNC_DEF <Z>
1106              Allow definitions of multiple functions at once in the form `fn1
1107              fn2...()'; if the option is not set, this causes a parse  error.
1108              Definition  of  multiple  functions with the function keyword is
1109              always allowed.  Multiple function  definitions  are  not  often
1110              used and can cause obscure errors.
1111
1112       MULTIOS <Z>
1113              Perform  implicit  tees  or  cats when multiple redirections are
1114              attempted (see the section `Redirection').
1115
1116       OCTAL_ZEROES <S>
1117              Interpret any integer constant beginning with a 0 as octal,  per
1118              IEEE  Std 1003.2-1992 (ISO 9945-2:1993).  This is not enabled by
1119              default as it causes problems with parsing of, for example, date
1120              and time strings with leading zeroes.
1121
1122              Sequences  of  digits indicating a numeric base such as the `08'
1123              component in `08#77' are always interpreted as decimal,  regard‐
1124              less of leading zeroes.
1125
1126       PIPE_FAIL
1127              By  default,  when  a pipeline exits the exit status recorded by
1128              the shell and returned by the shell variable $? reflects that of
1129              the rightmost element of a pipeline.  If this option is set, the
1130              exit status instead reflects the status of the rightmost element
1131              of  the  pipeline  that  was  non-zero,  or zero if all elements
1132              exited with zero status.
1133
1134       SOURCE_TRACE
1135              If set, zsh will print an informational message  announcing  the
1136              name of each file it loads.  The format of the output is similar
1137              to that for the XTRACE option, with the  message  <sourcetrace>.
1138              A  file  may be loaded by the shell itself when it starts up and
1139              shuts down  (Startup/Shutdown  Files)  or  by  the  use  of  the
1140              `source' and `dot' builtin commands.
1141
1142       TYPESET_SILENT
1143              If  this is unset, executing any of the `typeset' family of com‐
1144              mands with no options and a list of parameters that have no val‐
1145              ues  to  be assigned but already exist will display the value of
1146              the parameter.  If the option is set, they will  only  be  shown
1147              when  parameters  are selected with the `-m' option.  The option
1148              `-p' is available whether or not the option is set.
1149
1150       VERBOSE (-v, ksh: -v)
1151              Print shell input lines as they are read.
1152
1153       XTRACE (-x, ksh: -x)
1154              Print commands and their arguments as they  are  executed.   The
1155              output  is preceded by the value of $PS4, formatted as described
1156              in the section EXPANSION OF PROMPT SEQUENCES in zshmisc(1).
1157
1158   Shell Emulation
1159       APPEND_CREATE <K> <S>
1160              This option only applies when NO_CLOBBER (-C) is in effect.
1161
1162              If this option is not set, the shell will report an error when a
1163              append  redirection (>>) is used on a file that does not already
1164              exists (the traditional zsh behaviour of  NO_CLOBBER).   If  the
1165              option is set, no error is reported (POSIX behaviour).
1166
1167       BASH_REMATCH
1168              When  set,  matches  performed with the =~ operator will set the
1169              BASH_REMATCH array variable, instead of the  default  MATCH  and
1170              match  variables.   The  first element of the BASH_REMATCH array
1171              will contain the entire matched  text  and  subsequent  elements
1172              will contain extracted substrings.  This option makes more sense
1173              when KSH_ARRAYS is also set, so that the entire matched  portion
1174              is  stored  at  index  0  and the first substring is at index 1.
1175              Without this option, the  MATCH  variable  contains  the  entire
1176              matched text and the match array variable contains substrings.
1177
1178       BSD_ECHO <S>
1179              Make  the  echo builtin compatible with the BSD echo(1) command.
1180              This disables  backslashed  escape  sequences  in  echo  strings
1181              unless the -e option is specified.
1182
1183       CONTINUE_ON_ERROR
1184              If  a fatal error is encountered (see the section ERRORS in zsh‐
1185              misc(1)), and the code is running in a script,  the  shell  will
1186              resume  execution at the next statement in the script at the top
1187              level, in other words outside all functions or shell  constructs
1188              such  as  loops  and  conditions.   This mimics the behaviour of
1189              interactive shells, where the shell returns to the  line  editor
1190              to  read  a new command; it was the normal behaviour in versions
1191              of zsh before 5.0.1.
1192
1193       CSH_JUNKIE_HISTORY <C>
1194              A history reference without an event specifier will always refer
1195              to  the  previous  command.  Without this option, such a history
1196              reference refers to the same event as the previous history  ref‐
1197              erence  on  the current command line, defaulting to the previous
1198              command.
1199
1200       CSH_JUNKIE_LOOPS <C>
1201              Allow loop bodies to take the form `list; end'  instead  of  `do
1202              list; done'.
1203
1204       CSH_JUNKIE_QUOTES <C>
1205              Changes  the  rules  for single- and double-quoted text to match
1206              that of csh.  These require that embedded newlines  be  preceded
1207              by  a backslash; unescaped newlines will cause an error message.
1208              In double-quoted strings, it is made impossible to  escape  `$',
1209              ``'  or  `"' (and `\' itself no longer needs escaping).  Command
1210              substitutions are only expanded once, and cannot be nested.
1211
1212       CSH_NULLCMD <C>
1213              Do not use the values of NULLCMD and  READNULLCMD  when  running
1214              redirections  with no command.  This make such redirections fail
1215              (see the section `Redirection').
1216
1217       KSH_ARRAYS <K> <S>
1218              Emulate ksh array handling as  closely  as  possible.   If  this
1219              option  is  set, array elements are numbered from zero, an array
1220              parameter without subscript refers to the first element  instead
1221              of  the  whole  array, and braces are required to delimit a sub‐
1222              script (`${path[2]}' rather than just `$path[2]')  or  to  apply
1223              modifiers to any parameter (`${PWD:h}' rather than `$PWD:h').
1224
1225       KSH_AUTOLOAD <K> <S>
1226              Emulate  ksh function autoloading.  This means that when a func‐
1227              tion is autoloaded, the corresponding file is  merely  executed,
1228              and  must define the function itself.  (By default, the function
1229              is defined to the contents of the file.  However, the most  com‐
1230              mon  ksh-style case - of the file containing only a simple defi‐
1231              nition of the function - is always handled in the ksh-compatible
1232              manner.)
1233
1234       KSH_OPTION_PRINT <K>
1235              Alters the way options settings are printed: instead of separate
1236              lists of set and unset options, all options  are  shown,  marked
1237              `on' if they are in the non-default state, `off' otherwise.
1238
1239       KSH_TYPESET
1240              This  option is now obsolete: a better appropximation to the be‐
1241              haviour of other shells  is  obtained  with  the  reserved  word
1242              interface  to  declare,  export, float, integer, local, readonly
1243              and typeset.  Note that the option  is  only  applied  when  the
1244              reserved word interface is not in use.
1245
1246              Alters  the  way  arguments  to  the typeset family of commands,
1247              including declare, export, float, integer, local  and  readonly,
1248              are  processed.   Without  this  option, zsh will perform normal
1249              word splitting after command and parameter  expansion  in  argu‐
1250              ments  of  an  assignment; with it, word splitting does not take
1251              place in those cases.
1252
1253       KSH_ZERO_SUBSCRIPT
1254              Treat use of a subscript  of  value  zero  in  array  or  string
1255              expressions  as  a reference to the first element, i.e. the ele‐
1256              ment that usually has the subscript 1.  Ignored if KSH_ARRAYS is
1257              also set.
1258
1259              If  neither  this  option  nor KSH_ARRAYS is set, accesses to an
1260              element of an array or string  with  subscript  zero  return  an
1261              empty  element  or string, while attempts to set element zero of
1262              an array or string are treated as an error.   However,  attempts
1263              to  set  an  otherwise  valid subscript range that includes zero
1264              will succeed.  For example, if KSH_ZERO_SUBSCRIPT is not set,
1265
1266                     array[0]=(element)
1267
1268              is an error, while
1269
1270                     array[0,1]=(element)
1271
1272              is not and will replace the first element of the array.
1273
1274              This option is for compatibility  with  older  versions  of  the
1275              shell and is not recommended in new code.
1276
1277       POSIX_ALIASES <K> <S>
1278              When  this  option is set, reserved words are not candidates for
1279              alias expansion:  it is still possible to declare any of them as
1280              an  alias, but the alias will never be expanded.  Reserved words
1281              are described in the section RESERVED WORDS in zshmisc(1).
1282
1283              Alias expansion takes place while text is being read; hence when
1284              this  option is set it does not take effect until the end of any
1285              function or other piece of shell code parsed as one unit.   Note
1286              this  may  cause  differences  from  other  shells even when the
1287              option is in effect.  For example, when running a  command  with
1288              `zsh  -c',  or even `zsh -o posixaliases -c', the entire command
1289              argument is parsed as one unit, so aliases  defined  within  the
1290              argument  are  not  available even in later lines.  If in doubt,
1291              avoid use of aliases in non-interactive code.
1292
1293       POSIX_ARGZERO
1294              This option may be used to temporarily disable  FUNCTION_ARGZERO
1295              and  thereby  restore the value of $0 to the name used to invoke
1296              the shell (or as set by the -c command line option).   For  com‐
1297              patibility  with  previous versions of the shell, emulations use
1298              NO_FUNCTION_ARGZERO instead of POSIX_ARGZERO, which  may  result
1299              in  unexpected  scoping  of  $0 if the emulation mode is changed
1300              inside a function or script.  To avoid this,  explicitly  enable
1301              POSIX_ARGZERO in the emulate command:
1302
1303                     emulate sh -o POSIX_ARGZERO
1304
1305              Note that NO_POSIX_ARGZERO has no effect unless FUNCTION_ARGZERO
1306              was already enabled upon entry to the function or script.
1307
1308       POSIX_BUILTINS <K> <S>
1309              When this option is set the command builtin can be used to  exe‐
1310              cute  shell  builtin  commands.  Parameter assignments specified
1311              before shell functions and special builtins are kept  after  the
1312              command  completes  unless  the special builtin is prefixed with
1313              the command builtin.  Special builtins are  .,  :,  break,  con‐
1314              tinue,  declare,  eval,  exit, export, integer, local, readonly,
1315              return, set, shift, source, times, trap and unset.
1316
1317              In addition, various error conditions associated with the  above
1318              builtins  or  exec  cause a non-interactive shell to exit and an
1319              interactive shell to return to its top-level processing.
1320
1321              Furthermore, functions and shell builtins are not executed after
1322              an  exec  prefix; the command to be executed must be an external
1323              command found in the path.
1324
1325              Furthermore, the getopts builtin behaves in  a  POSIX-compatible
1326              fashion in that the associated variable OPTIND is not made local
1327              to functions.
1328
1329              Moreover, the warning and special exit code from [[ -o non_exis‐
1330              tent_option ]] are suppressed.
1331
1332       POSIX_IDENTIFIERS <K> <S>
1333              When  this option is set, only the ASCII characters a to z, A to
1334              Z, 0 to 9 and _ may be  used  in  identifiers  (names  of  shell
1335              parameters and modules).
1336
1337              In  addition, setting this option limits the effect of parameter
1338              substitution with no  braces,  so  that  the  expression  $#  is
1339              treated  as the parameter $# even if followed by a valid parame‐
1340              ter name.  When it is unset, zsh allows expressions of the  form
1341              $#name  to  refer to the length of $name, even for special vari‐
1342              ables, for example in expressions such as $#- and $#*.
1343
1344              Another difference is that with the option set assignment to  an
1345              unset  variable  in arithmetic context causes the variable to be
1346              created as a scalar rather than a numeric type.  So after `unset
1347              t;  ((  t  =  3 ))'. without POSIX_IDENTIFIERS set t has integer
1348              type, while with it set it has scalar type.
1349
1350              When the option is unset  and  multibyte  character  support  is
1351              enabled  (i.e.  it  is  compiled  in and the option MULTIBYTE is
1352              set), then additionally any alphanumeric characters in the local
1353              character set may be used in identifiers.  Note that scripts and
1354              functions written with this feature are not portable,  and  also
1355              that  both  options must be set before the script or function is
1356              parsed; setting them during execution is not sufficient  as  the
1357              syntax  variable=value  has  already  been  parsed  as a command
1358              rather than an assignment.
1359
1360              If multibyte character support is not compiled  into  the  shell
1361              this  option  is ignored; all octets with the top bit set may be
1362              used in identifiers.  This is non-standard  but  is  the  tradi‐
1363              tional zsh behaviour.
1364
1365       POSIX_STRINGS <K> <S>
1366              This  option affects processing of quoted strings.  Currently it
1367              only affects the behaviour of null characters, i.e. character  0
1368              in the portable character set corresponding to US ASCII.
1369
1370              When  this  option  is  not set, null characters embedded within
1371              strings of the form $'...' are treated as  ordinary  characters.
1372              The  entire  string is maintained within the shell and output to
1373              files where necessary, although owing  to  restrictions  of  the
1374              library  interface the string is truncated at the null character
1375              in file names, environment variables, or in arguments to  exter‐
1376              nal programs.
1377
1378              When  this  option is set, the $'...' expression is truncated at
1379              the null character.  Note  that  remaining  parts  of  the  same
1380              string beyond the termination of the quotes are not truncated.
1381
1382              For example, the command line argument a$'b\0c'd is treated with
1383              the option off as the characters a, b, null, c, d, and with  the
1384              option on as the characters a, b, d.
1385
1386       POSIX_TRAPS <K> <S>
1387              When  this  option  is set, the usual zsh behaviour of executing
1388              traps for EXIT on exit from shell functions is  suppressed.   In
1389              that case, manipulating EXIT traps always alters the global trap
1390              for exiting the shell; the LOCAL_TRAPS option is ignored for the
1391              EXIT  trap.   Furthermore, a return statement executed in a trap
1392              with no argument passes back from the function  the  value  from
1393              the surrounding context, not from code executed within the trap.
1394
1395       SH_FILE_EXPANSION <K> <S>
1396              Perform  filename expansion (e.g., ~ expansion) before parameter
1397              expansion, command substitution, arithmetic expansion and  brace
1398              expansion.  If this option is unset, it is performed after brace
1399              expansion, so things like `~$USERNAME' and `~{pfalstad,rc}' will
1400              work.
1401
1402       SH_NULLCMD <K> <S>
1403              Do  not  use  the  values  of NULLCMD and READNULLCMD when doing
1404              redirections, use `:' instead (see the section `Redirection').
1405
1406       SH_OPTION_LETTERS <K> <S>
1407              If this option is set the shell tries to interpret single letter
1408              options  (which  are  used  with  set and setopt) like ksh does.
1409              This also affects the value of the - special parameter.
1410
1411       SH_WORD_SPLIT (-y) <K> <S>
1412              Causes field splitting to be  performed  on  unquoted  parameter
1413              expansions.   Note  that this option has nothing to do with word
1414              splitting.  (See the section `Parameter Expansion'.)
1415
1416       TRAPS_ASYNC
1417              While waiting for a program to  exit,  handle  signals  and  run
1418              traps  immediately.   Otherwise  the  trap  is run after a child
1419              process has exited.  Note this does  not  affect  the  point  at
1420              which  traps  are  run for any case other than when the shell is
1421              waiting for a child process.
1422
1423   Shell State
1424       INTERACTIVE (-i, ksh: -i)
1425              This is an interactive shell.  This option is set upon initiali‐
1426              sation  if  the  standard  input is a tty and commands are being
1427              read from standard input.  (See the discussion  of  SHIN_STDIN.)
1428              This  heuristic may be overridden by specifying a state for this
1429              option on the command line.  The value of this option  can  only
1430              be  changed  via  flags supplied at invocation of the shell.  It
1431              cannot be changed once zsh is running.
1432
1433       LOGIN (-l, ksh: -l)
1434              This is a login shell.  If this option is  not  explicitly  set,
1435              the  shell  becomes  a login shell if the first character of the
1436              argv[0] passed to the shell is a `-'.
1437
1438       PRIVILEGED (-p, ksh: -p)
1439              Turn on privileged mode. Typically this is used when  script  is
1440              to  be run with elevated privileges. This should be done as fol‐
1441              lows directly with the -p option to zsh so that it takes  effect
1442              during startup.
1443
1444                     #!/bin/zsh -p
1445
1446              The  option is enabled automatically on startup if the effective
1447              user (group) ID is not equal to the real  user  (group)  ID.  In
1448              this  case, turning the option off causes the effective user and
1449              group IDs to be set to the real user and  group  IDs.  Be  aware
1450              that  if  that fails the shell may be running with different IDs
1451              than was intended so a script should check for failure  and  act
1452              accordingly, for example:
1453
1454                     unsetopt privileged || exit
1455
1456              The  PRIVILEGED option disables sourcing user startup files.  If
1457              zsh  is  invoked  as  `sh'  or  `ksh'  with  this  option   set,
1458              /etc/suid_profile  is sourced (after /etc/profile on interactive
1459              shells). Sourcing ~/.profile is disabled and the contents of the
1460              ENV variable is ignored. This option cannot be changed using the
1461              -m option of setopt and unsetopt, and changing it inside a func‐
1462              tion  always changes it globally regardless of the LOCAL_OPTIONS
1463              option.
1464
1465       RESTRICTED (-r)
1466              Enables restricted mode.  This option cannot  be  changed  using
1467              unsetopt,  and  setting  it  inside a function always changes it
1468              globally regardless of the LOCAL_OPTIONS option.  See  the  sec‐
1469              tion `Restricted Shell'.
1470
1471       SHIN_STDIN (-s, ksh: -s)
1472              Commands  are  being read from the standard input.  Commands are
1473              read from standard input if no command is specified with -c  and
1474              no  file of commands is specified.  If SHIN_STDIN is set explic‐
1475              itly on the command line, any argument that would otherwise have
1476              been  taken as a file to run will instead be treated as a normal
1477              positional parameter.   Note  that  setting  or  unsetting  this
1478              option on the command line does not necessarily affect the state
1479              the option will have while the shell is running - that is purely
1480              an  indicator of whether or not commands are actually being read
1481              from standard input.  The value  of  this  option  can  only  be
1482              changed  via flags supplied at invocation of the shell.  It can‐
1483              not be changed once zsh is running.
1484
1485       SINGLE_COMMAND (-t, ksh: -t)
1486              If the shell is reading from standard input, it  exits  after  a
1487              single  command  has  been  executed.  This also makes the shell
1488              non-interactive, unless the INTERACTIVE option is explicitly set
1489              on  the  command  line.   The  value  of this option can only be
1490              changed via flags supplied at invocation of the shell.  It  can‐
1491              not be changed once zsh is running.
1492
1493   Zle
1494       BEEP (+B) <D>
1495              Beep on error in ZLE.
1496
1497       COMBINING_CHARS
1498              Assume  that  the  terminal  displays  combining characters cor‐
1499              rectly.  Specifically, if a base alphanumeric character is  fol‐
1500              lowed  by  one or more zero-width punctuation characters, assume
1501              that the zero-width characters will be  displayed  as  modifica‐
1502              tions to the base character within the same width.  Not all ter‐
1503              minals handle this.  If this option is not set, zero-width char‐
1504              acters are displayed separately with special mark-up.
1505
1506              If  this  option  is  set, the pattern test [[:WORD:]] matches a
1507              zero-width punctuation character on the assumption that it  will
1508              be  used as part of a word in combination with a word character.
1509              Otherwise the base shell does not  handle  combining  characters
1510              specially.
1511
1512       EMACS  If  ZLE  is  loaded,  turning  on this option has the equivalent
1513              effect of `bindkey -e'.  In addition, the VI  option  is  unset.
1514              Turning it off has no effect.  The option setting is not guaran‐
1515              teed to reflect the current keymap.  This option is provided for
1516              compatibility; bindkey is the recommended interface.
1517
1518       OVERSTRIKE
1519              Start up the line editor in overstrike mode.
1520
1521       SINGLE_LINE_ZLE (-M) <K>
1522              Use single-line command line editing instead of multi-line.
1523
1524              Note  that  although  this  is on by default in ksh emulation it
1525              only provides superficial compatibility with the ksh line editor
1526              and reduces the effectiveness of the zsh line editor.  As it has
1527              no effect on shell syntax, many users may wish to  disable  this
1528              option when using ksh emulation interactively.
1529
1530       VI     If  ZLE  is  loaded,  turning  on this option has the equivalent
1531              effect of `bindkey -v'.  In addition, the EMACS option is unset.
1532              Turning it off has no effect.  The option setting is not guaran‐
1533              teed to reflect the current keymap.  This option is provided for
1534              compatibility; bindkey is the recommended interface.
1535
1536       ZLE (-Z)
1537              Use  the  zsh line editor.  Set by default in interactive shells
1538              connected to a terminal.
1539

OPTION ALIASES

1541       Some options have alternative names.  These aliases are never used  for
1542       output,  but  can be used just like normal option names when specifying
1543       options to the shell.
1544
1545       BRACE_EXPAND
1546              NO_IGNORE_BRACES (ksh and bash compatibility)
1547
1548       DOT_GLOB
1549              GLOB_DOTS (bash compatibility)
1550
1551       HASH_ALL
1552              HASH_CMDS (bash compatibility)
1553
1554       HIST_APPEND
1555              APPEND_HISTORY (bash compatibility)
1556
1557       HIST_EXPAND
1558              BANG_HIST (bash compatibility)
1559
1560       LOG    NO_HIST_NO_FUNCTIONS (ksh compatibility)
1561
1562       MAIL_WARN
1563              MAIL_WARNING (bash compatibility)
1564
1565       ONE_CMD
1566              SINGLE_COMMAND (bash compatibility)
1567
1568       PHYSICAL
1569              CHASE_LINKS (ksh and bash compatibility)
1570
1571       PROMPT_VARS
1572              PROMPT_SUBST (bash compatibility)
1573
1574       STDIN  SHIN_STDIN (ksh compatibility)
1575
1576       TRACK_ALL
1577              HASH_CMDS (ksh compatibility)
1578

SINGLE LETTER OPTIONS

1580   Default set
1581       -0     CORRECT
1582       -1     PRINT_EXIT_VALUE
1583       -2     NO_BAD_PATTERN
1584       -3     NO_NOMATCH
1585       -4     GLOB_DOTS
1586       -5     NOTIFY
1587       -6     BG_NICE
1588       -7     IGNORE_EOF
1589       -8     MARK_DIRS
1590       -9     AUTO_LIST
1591       -B     NO_BEEP
1592       -C     NO_CLOBBER
1593       -D     PUSHD_TO_HOME
1594       -E     PUSHD_SILENT
1595       -F     NO_GLOB
1596       -G     NULL_GLOB
1597       -H     RM_STAR_SILENT
1598       -I     IGNORE_BRACES
1599       -J     AUTO_CD
1600       -K     NO_BANG_HIST
1601       -L     SUN_KEYBOARD_HACK
1602       -M     SINGLE_LINE_ZLE
1603       -N     AUTO_PUSHD
1604       -O     CORRECT_ALL
1605       -P     RC_EXPAND_PARAM
1606       -Q     PATH_DIRS
1607       -R     LONG_LIST_JOBS
1608       -S     REC_EXACT
1609       -T     CDABLE_VARS
1610       -U     MAIL_WARNING
1611       -V     NO_PROMPT_CR
1612       -W     AUTO_RESUME
1613       -X     LIST_TYPES
1614       -Y     MENU_COMPLETE
1615       -Z     ZLE
1616       -a     ALL_EXPORT
1617       -e     ERR_EXIT
1618       -f     NO_RCS
1619       -g     HIST_IGNORE_SPACE
1620       -h     HIST_IGNORE_DUPS
1621       -i     INTERACTIVE
1622       -k     INTERACTIVE_COMMENTS
1623       -l     LOGIN
1624       -m     MONITOR
1625       -n     NO_EXEC
1626       -p     PRIVILEGED
1627       -r     RESTRICTED
1628       -s     SHIN_STDIN
1629       -t     SINGLE_COMMAND
1630       -u     NO_UNSET
1631       -v     VERBOSE
1632       -w     CHASE_LINKS
1633       -x     XTRACE
1634       -y     SH_WORD_SPLIT
1635
1636   sh/ksh emulation set
1637       -C     NO_CLOBBER
1638       -T     TRAPS_ASYNC
1639       -X     MARK_DIRS
1640       -a     ALL_EXPORT
1641       -b     NOTIFY
1642       -e     ERR_EXIT
1643       -f     NO_GLOB
1644       -i     INTERACTIVE
1645       -l     LOGIN
1646       -m     MONITOR
1647       -n     NO_EXEC
1648       -p     PRIVILEGED
1649       -r     RESTRICTED
1650       -s     SHIN_STDIN
1651       -t     SINGLE_COMMAND
1652       -u     NO_UNSET
1653       -v     VERBOSE
1654       -x     XTRACE
1655
1656   Also note
1657       -A     Used by set for setting arrays
1658       -b     Used on the command line to specify end of option processing
1659       -c     Used on the command line to specify a single command
1660       -m     Used by setopt for pattern-matching option setting
1661       -o     Used in all places to allow use of long option names
1662       -s     Used by set to sort positional parameters
1663
1664
1665
1666zsh 5.6.2                     September 14, 2018                 ZSHOPTIONS(1)
Impressum