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