diff --git a/docs/internals/shell_options.md b/docs/internals/shell_options.md new file mode 100644 index 0000000..9fddca5 --- /dev/null +++ b/docs/internals/shell_options.md @@ -0,0 +1,509 @@ +# List of shell options + +![](keywords>bash shell scripting options runtime variable behaviour) + +This information was taken from a Bash version \"`4.1`\", every now and +then new options are added, so likely, this list isn\'t complete. + +The shell-options can be set with the [shopt builtin +command](/commands/builtin/shopt). + +## Shell options + +### autocd + + Option: `autocd` Since: 4.0-alpha + ------------- ------------------ ---------- ----------- + Shell mode: interactive only Default: off + +If set, a command name that is the name of a directory is executed as if +it were the argument to the cd command. + +### assoc_expand_once + + Option: `assoc_expand_once` Since: 5.0-alpha + ------------- --------------------- ---------- ----------- + Shell mode: all Default: off + +If set, Bash attempts to expand associative array options only once. + +### cdable_vars + + Option: `cdable_vars` Since: unknown + ------------- --------------- ---------- --------- + Shell mode: all Default: off + +Treat every **non-directory argument** to the `cd`-command as variable +name containing a directory to `cd` into. + +### cdspell + + Option: `cdspell` Since: unknown + ------------- ------------------ ---------- --------- + Shell mode: interactive only Default: off + +If set, minor errors in the spelling of a directory component in a cd +command will be corrected. The errors checked for are transposed +characters, a missing character, and one character too many. If a +correction is found, the corrected file name is printed, and the command +proceeds. + +### checkhash + + Option: `checkhash` Since: unknown + ------------- ------------- ---------- --------- + Shell mode: all Default: off + +If set, Bash checks that a command found in the hash table exists before +trying to execute it. If a hashed command no longer exists, a normal +path search is performed. + +### checkjobs + + Option: `checkjobs` Since: 4.0-alpha + ------------- ------------------ ---------- ----------- + Shell mode: interactive only Default: off + +If set, Bash lists the status of any stopped and running jobs before +exiting an interactive shell. If any jobs are running, this causes the +exit to be deferred until a second exit is attempted without an +intervening command. The shell always postpones exiting if any jobs are +stopped. + +### checkwinsize + + Option: `checkwinsize` Since: unknown + ------------- ---------------- ---------- --------- + Shell mode: all Default: on + +If set, Bash checks the window size after each command and, if +necessary, updates the values of the variables +[LINES](/syntax/shellvars#LINES) and +[COLUMNS](/syntax/shellvars#COLUMNS). + +### cmdhist + + Option: `cmdhist` Since: unknown + ------------- ----------- ---------- --------- + Shell mode: all Default: off + +If set, Bash attempts to save all lines of a multiple-line command in +the same history entry. This allows easy re-editing of multi-line +commands. + +### compat31 + + Option: `compat31` Since: 3.2 + ------------- ------------ ---------- ----- + Shell mode: all Default: off + +Compatiblity mode for Bash 3.1 + +### compat32 + + Option: `compat32` Since: 4.0 + ------------- ------------ ---------- ----- + Shell mode: all Default: off + +Compatiblity mode for Bash 3.2 + +### compat40 + + Option: `compat40` Since: 4.1-beta + ------------- ------------ ---------- ---------- + Shell mode: all Default: off + +Compatiblity mode for Bash 4.0 + +### compat41 + + Option: `compat41` Since: 4.2-alpha + ------------- ------------ ---------- ----------- + Shell mode: all Default: off + +Compatiblity mode for Bash 4.1 + +### compat42 + + Option: `compat42` Since: 4.3-alpha + ------------- ------------ ---------- ----------- + Shell mode: all Default: off + +Compatiblity mode for Bash 4.2 + +### compat43 + + Option: `compat43` Since: 4.4-alpha + ------------- ------------ ---------- ----------- + Shell mode: all Default: off + +Compatiblity mode for Bash 4.3 + +### compat44 + + Option: `compat44` Since: 5.0-alpha + ------------- ------------ ---------- ----------- + Shell mode: all Default: off + +Compatiblity mode for Bash 4.4 + +### direxpand + + Option: `direxpand` Since: 4.3-alpha + ------------- ------------- ---------- ------------------------------------------------------------------------ + Shell mode: all Default: off (unless changed on compile-time with `--enable-direxpand-default`) + +If set, bash replaces directory names with the results of word expansion +when performing filename completion. This changes the contents of the +readline editing buffer. If not set, bash attempts to preserve what the +user typed. + +### dirspell + + Option: `dirspell` Since: 4.0-alpha + ------------- ------------ ---------- ----------- + Shell mode: all Default: off + +If set, Bash will perform spelling corrections on directory names to +match a glob. + +### dotglob + + Option: `dotglob` Since: unknown + ------------- ----------- ---------- --------- + Shell mode: all Default: off + +If set, Bash includes filenames beginning with a `.` (dot) in the +results of [pathname expansion](/syntax/expansion/globs). + +### execfail + + Option: `execfail` Since: unknown + ------------- ----------------- ---------- --------- + Shell mode: non-interactive Default: off + +If set, a non-interactive shell will not exit if it cannot execute the +file specified as an argument to the `exec`-builtin command. An +interactive shell does not exit if `exec` fails. + +### expand_aliases + + Option: `expand_aliases` Since: unknown + ------------- ------------------ ---------- ----------------------------------------- + Shell mode: all Default: on (interactive), off (non-interactive) + +If set, aliases are expanded. This option is enabled by default for +interactive shells. + +### extdebug + + Option: `extdebug` Since: 3.0-alpha + ------------- ------------ ---------- ----------- + Shell mode: all Default: off + +If set, behavior intended for use by debuggers is enabled. + +### extglob + + Option: `extglob` Since: 2.02-alpha1 + ------------- ----------- ---------- ------------- + Shell mode: all Default: off + +If set, the extended [pattern matching](/syntax/pattern) features are +enabled. See the important note below under [Parser +configurations](#parser_configurations). + +### extquote + + Option: `extquote` Since: 3.0-alpha (?) + ------------- ------------ ---------- --------------- + Shell mode: all Default: on + +If set, `$'string'` and `$"string"` quoting is performed within +[parameter expansions](/syntax/pe) enclosed in double quotes. See the +important note below under [Parser +configurations](#parser_configurations). + +### failglob + + Option: `failglob` Since: 3.0-alpha + ------------- ------------ ---------- ----------- + Shell mode: all Default: off + +If set, patterns which fail to match filenames during pathname expansion +result in an error message. + +### force_fignore + + Option: `force_fignore` Since: 3.0-alpha + ------------- ----------------- ---------- ----------- + Shell mode: interactive Default: on + +If set, the suffixes specified by the +[FIGNORE](/syntax/shellvars#FIGNORE) shell variable cause words to be +ignored when performing word completion even if the ignored words are +the only possible completions. This option is enabled by default. + +### globasciiranges + + Option: `globasciiranges` Since: 4.3-alpha + ------------- ------------------- ---------- ----------------------------------- + Shell mode: all Default: on (configurable at compile time) + +If set, range expressions used in pattern matching behave as if in the +traditional C locale when performing comparisons. That is, the current +locale\'s collating sequence is not taken into account, so b will not +collate between A and B, and upper-case and lower-case ASCII characters +will collate together. + +### globstar + + Option: `globstar` Since: 4.0-alpha + ------------- ------------ ---------- ----------- + Shell mode: all Default: off + +If set, recursive globbing with `**` is enabled. + +### gnu_errfmt + + Option: `gnu_errfmt` Since: 3.0-alpha + ------------- -------------- ---------- ----------- + Shell mode: all Default: off + +If set, shell error messages are written in the \"standard GNU error +message format\". + +### histappend + + Option: `histappend` Since: unknown + ------------- ----------------- ---------- --------- + Shell mode: interactive (?) Default: off + +If set, the history list is appended to the file named by the value of +the [HISTFILE](/syntax/shellvars#HISTFILE) variable when the shell +exits, rather than overwriting the file. + +### histreedit + + Option: `histreedit` Since: unknown + ------------- ----------------- ---------- --------- + Shell mode: interactive (?) Default: off + +If set, and readline is being used, a user is given the opportunity to +re-edit a failed history substitution. + +### histverify + + Option: `histverify` Since: unknown + ------------- ----------------- ---------- --------- + Shell mode: interactive (?) Default: off + +Allow to review a history substitution result by loading the resulting +line into the editing buffer, rather than directly executing it. + +### hostcomplete + + Option: `hostcomplete` Since: 2.0-alpha3 + ------------- ----------------- ---------- ------------ + Shell mode: interactive (?) Default: on + +If set, Bash completion also completes hostnames. On by default. + +### huponexit + + Option: `huponexit` Since: 2.02-alpha1 + ------------- ------------------- ---------- ------------- + Shell mode: interactive login Default: off + +If set, Bash will send the `SIGHUP` signal to all jobs when an +interactive login shell exits. + +### interactive_comments + + Option: `interactive_comments` Since: unknown + ------------- ------------------------ ---------- --------- + Shell mode: interactive Default: on + +Allow [commenting](/scripting/basics#comments) in interactive shells, on +by default. + +### lastpipe + + Option: `lastpipe` Since: 4.2-alpha + ------------- ------------ ---------- ----------- + Shell mode: all Default: off + +If set, **and job control is not active**, the shell runs the last +command of a pipeline not executed in the background in the current +shell environment. + +### lithist + + Option: `lithist` Since: unknown + ------------- ------------- ---------- --------- + Shell mode: interactive Default: off + +If set, and the [#cmdhist](#cmdhist) option is enabled, multi-line +commands are saved to the history with embedded newlines rather than +using semicolon separators where possible. + +### localvar_inherit + + Option: `localvar_inherit` Since: 5.0-alpha + ------------- -------------------- ---------- ----------- + Shell mode: all Default: off + +If this option is set, a local variable inherits the value of a variable +with the same name at the nearest preceding scope. + +### login_shell + + Option: `login_shell` Since: 2.05a-alpha1 + ------------- --------------- ---------- -------------- + Shell mode: all Default: n/a + +The option is set when Bash is a login shell. This is a readonly option. + +### mailwarn + + Option: `mailwarn` Since: unknown + ------------- ----------------- ---------- --------- + Shell mode: interactive (?) Default: off + +If set, and a file that Bash is checking for mail has been accessed +since the last time it was checked, the message \"The mail in mailfile +has been read\" is displayed. + +### no_empty_cmd_completion + + Option: `mailwarn` Since: unknown + ------------- ----------------- ---------- --------- + Shell mode: interactive (?) Default: off + +If set, and readline is being used, Bash will not attempt to search the +PATH for possible completions when completion is attempted on an empty +line. + +### nocaseglob + + Option: `nocaseglob` Since: 2.02-alpha1 + ------------- -------------- ---------- ------------- + Shell mode: all Default: off + +If set, Bash matches filenames in a case-insensitive fashion when +performing pathname expansion. + +### nocasematch + + Option: `nocasematch` Since: 3.1-alpha1 + ------------- --------------- ---------- ------------ + Shell mode: all Default: off + +If set, Bash matches patterns in a case-insensitive fashion when +performing matching while executing `case` or `[[` conditional commands. + +### nullglob + + Option: `nullglob` Since: unknown + ------------- ------------ ---------- --------- + Shell mode: all Default: off + +If set, Bash allows patterns which match no files to expand to a null +string, rather than themselves. + +### progcomp + + Option: `progcomp` Since: 2.04-alpha1 + ------------- ----------------- ---------- ------------- + Shell mode: interactive (?) Default: on + +If set, the programmable completion facilities are enabled. This option +is enabled by default. + +### promptvars + + Option: `promptvars` Since: unknown + ------------- -------------- ---------- --------- + Shell mode: interactive Default: on + +If set, prompt strings undergo parameter expansion, command +substitution, arithmetic expansion, and quote removal after being +expanded using the prompt special sequences. This option is enabled by +default. + +### restricted_shell + + Option: `restricted_shell` Since: 2.03-alpha + ------------- -------------------- ---------- ------------ + Shell mode: interactive (?) Default: off + +The option is set when Bash is a restricted shell. This is a readonly +option. + +### shift_verbose + + Option: `shift_verbose` Since: unknown + ------------- ----------------- ---------- ----------------------- + Shell mode: all Default: off, on in POSIX mode + +If set, the shift builtin prints an error message when the shift count +exceeds the number of positional parameters. + +### sourcepath + + Option: `sourcepath` Since: unknown + ------------- -------------- ---------- --------- + Shell mode: all Default: on + +If set, the source builtin command uses the value of PATH to find the +directory containing the file supplied as an argument. This option is +enabled by default. + +### syslog_history + + Option: `syslog_history` Since: 5.0-alpha + ------------- ------------------ ---------- ----------- + Shell mode: unknown Default: off + +If set, the shell history is sent to syslog. + +This option is undocumented and available only if the shell supports +syslog. + +### xpg_echo + + Option: `xpg_echo` Since: 2.04-beta1 + ------------- ------------ ---------- ------------ + Shell mode: all Default: off + +If set, the `echo`-builtin command expands backslash-escape sequences by +default (POSIX, SUS, XPG). + +## Parser configurations + +Parser configurations change the way the Bash parser recognizes the +syntax when parsing a line. This, of course, is impossible for a line +that already was parsed. + +There are two options that influence the parsing this way: + +- `extglob` +- `extquote` + +Consequence: You **can\'t** use the new syntax (e.g. the extended +globbing syntax) and the command to enable it **in the same line**. + + $ shopt -s extglob; echo !(*.txt) # this is the WRONG way! + -bash: syntax error near unexpected token `(' + +You have to configure the parser **before** a line with new syntax is +parsed: + + $ shopt -s extglob # standalone - CORRECT way! + $ echo !(*.txt) + ... + +## See also + +- Internal: [shopt builtin command](/commands/builtin/shopt) +- Internal: [set builtin command](/commands/builtin/set)