Shell options

Shell options control the behavior of the shell. You can enable (set) or disable (unset) them using command line arguments at startup or with the set built-in during a shell session.

Enabling and disabling options

You can specify shell options as command line arguments when starting the shell, or with the set built-in. In yash, all options have a long name, and some also have a short name.

Options set at startup take effect before the shell reads and executes commands. Options set with set affect the current shell session. Some options are only available at startup; others can be changed at any time. The syntax is the same in both cases.

Long option names

Long options start with --. For example, to enable the allexport option at startup:

yash3 --allexport

You can also specify long options with the -o option:

yash3 -o allexport

Only alphanumeric characters matter in long option names, and they are case-insensitive. For example, --all-export, --ALLEXPORT, and ---All*Ex!PorT all enable allexport.

Long option names can be abbreviated if unambiguous. For example, --cl enables clobber:

$ set --cl
$ set --c
error: ambiguous option name "--c"
 --> <stdin>:2:5
  |
2 | set --c
  | --- ^^^ --c
  | |
  | info: executing the set built-in
  |

Note: Future versions may add more options, so abbreviations that work now may become ambiguous later. For forward compatibility, use full option names.

To disable a long option, prepend no to the name:

yash3 --noallexport

Or use ++ instead of --:

yash3 ++allexport

Or use +o instead of -o:

yash3 +o allexport

If you use both + and no, it is a double negation and enables the option:

yash3 +o noallexport

Short option names

Some options have short names, specified as a single character. For example, to enable allexport with its short name:

yash3 -a

To disable it:

yash3 +a

You can combine multiple short options in one argument:

yash3 -aex

Some short options negate long options. For example, -C is the same as --noclobber (disables clobber). To enable clobber with its short name, use +C.

Viewing current options

To see current shell options, use set -o with no arguments:

$ set -o
allexport        off
clobber          on
cmdline          off
errexit          off
exec             on
glob             on
hashondefinition off
ignoreeof        off
interactive      off
log              on
login            off
monitor          off
notify           off
posixlycorrect   off
stdin            on
unset            on
verbose          off
vi               off
xtrace           off

set +o prints options in a format that can be used to restore them:

$ set +o
set +o allexport
set -o clobber
#set +o cmdline
set +o errexit
set -o exec
set -o glob
set +o hashondefinition
set +o ignoreeof
#set +o interactive
set -o log
set +o login
set +o monitor
set +o notify
set +o posixlycorrect
#set -o stdin
set -o unset
set +o verbose
set +o vi
set +o xtrace

$ set +o allexport
$ savedoptions=$(set +o)
$ set -o allexport
$ eval "$savedoptions"
$ set -o | grep allexport
allexport        off

The - special parameter contains the currently set short options. For example, if -i and -m are set, the value of - is im. Options without a short name are not included. Short options that negate long options are included when the long option is unset.

$ set -a -o noclobber
$ echo "$-"
aCs

Option list

Below is a list of all shell options in yash-rs, with their long and short names, and a brief description. Unless noted, all options are disabled by default.

• allexport (-a): If set, all variables assigned in the shell are exported.

• clobber (+C): If set (default), the > redirection operator overwrites existing files. If unset, > fails if the file exists. The >| operator always overwrites files.

• cmdline (-c): If set, the shell executes the first operand from the command line as a command. Mutually exclusive with stdin, and only settable at startup.

• errexit (-e): If set, the shell exits if a command fails. Useful for scripts to stop on errors. See Exiting on errors for details.

• exec (+n): If set (default), the shell executes commands. If unset, it only parses commands (useful for syntax checking).

  • Once unset, it cannot be set again in the same session.
  • In interactive shells, this option is ignored and commands are always executed.

• glob (+f): If set (default), the shell performs pathname expansion on words containing metacharacters. If unset, pathname expansion is skipped.

• hashondefinition (-h): Deprecated and has no effect. Remains for compatibility.

  • The short name -h is currently a synonym for --hashondefinition, but this may change.
  • Many shells implement -h differently, so behavior may vary.

• ignoreeof: If set, the shell ignores end-of-file (usually Ctrl+D) and does not exit. See Preventing accidental exits.

  • Only takes effect if the shell is interactive and input is a terminal.

• interactive (-i): If set, the shell is interactive.

  • Enabled on startup if stdin is enabled and standard input and error are terminals.

• log: Deprecated and has no effect. Remains for compatibility.

• login (-l): If set, the shell behaves as a login shell. Only settable at startup.

  • ⚠️ Currently has no effect in yash-rs. In the future, login shells will read extra initialization files.

• monitor (-m): If set, the shell performs job control (allows managing background and foreground jobs).

  • Enabled by default in interactive shells.

• notify (-b): If set, the shell notifies you of background job completions and suspensions as soon as they occur. If unset, notifications are delayed until the next prompt.

  • ⚠️ Currently has no effect in yash-rs. In the future, it will enable immediate notifications for background jobs.
  • Only takes effect if interactive and monitor are enabled.

• pipefail: If set, the shell returns the exit status of the last command in a pipeline that failed, instead of the last command’s exit status. See Catching errors across pipeline components for details.

  • ⚠️ Not yet implemented in yash-rs.

• posixlycorrect: If set, the shell behaves as POSIX-compliant as possible. Useful for portable scripts.

  • Enabled on startup if the shell is started as sh.
  • When unset, yash-rs may deviate from POSIX in some areas.

• stdin (-s): If set, the shell reads commands from standard input. Mutually exclusive with cmdline, and only settable at startup.

  • Enabled if cmdline is not set and the shell is started with no operands.

• unset (+u): If set (default), the shell expands unset variables to an empty string. If unset, expanding an unset variable raises an error. See Unset parameters (in parameter expansion) and Variables (in arithmetic expression) for details.

• verbose (-v): If set, the shell prints each command before executing it. See Reviewing command input for details.

• vi: If set, the shell uses vi-style keybindings for command line editing.

  • ⚠️ Currently has no effect in yash-rs. In the future, it will enable vi-style editing in interactive shells.

• xtrace (-x): If set, the shell prints each field after expansion, before executing it. See Tracing command execution for details.

Compatibility

The syntax and options specified in POSIX.1-2024 are much more limited than those in yash-rs. For portable scripts, use only POSIX-specified syntax and options.

POSIX.1-2024 syntax:

• Enable a long option: set -o optionname (no -- prefix).
• Disable a long option: set +o optionname (no ++ prefix).
• Long options are case-sensitive, must be spelled out in full, and cannot contain extra symbols.
• No support for no-prefix inversion of long options.
• Enable a short option: - followed by the option character.
• Disable a short option: + followed by the option character.
• Short options can be combined after the - or + prefix.
• View current options: set -o or set +o.

POSIX.1-2024 options:

• -a, -o allexport
• -b, -o notify
• -C, -o noclobber
• -c
• -e, -o errexit
• -f, -o noglob
• -h
• -i
• -m, -o monitor
• -n, -o noexec
• -s
• -u, -o nounset
• -v, -o verbose
• -x, -o xtrace
• -o ignoreeof
• -o nolog
• -o pipefail
• -o vi