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