Shell · XB Field Notes

Bash history is your searchable command log

Mon, 28 Feb 2028 00:00:00 +0000

A useful command history saves retyping, but it is not a complete record of everything executed. Bash normally enables history in interactive shells, and settings can exclude entries or limit retention. The searchable list in a running shell and the history file on disk are separate states. That distinction explains why a command may be visible in one terminal, absent in another, and lost when an unwritten session ends unexpectedly.

Session memory differs from the file

HISTSIZE limits the in-memory history entries; HISTFILESIZE limits the saved file’s lines. Multiline commands and timestamp records mean that line counts and command counts are not interchangeable. HISTFILE selects the file, normally the user’s Bash history file. An unset or empty value prevents ordinary saving, and an unwritable location can leave apparently healthy in-memory recall with no persistent record.

Bash records command text before parameter expansion but after history expansion, subject to HISTCONTROL and HISTIGNORE. A saved line containing a variable therefore does not necessarily reveal the value used during the original execution. Current directories, aliases, functions, environment values, and external files can all change before a command is recalled. History preserves useful input, not a reproducible execution environment or a trustworthy audit trail.

Appending does not refresh other terminals

On normal exit, Bash saves history; histappend selects appending rather than overwriting the file. Without earlier writes, abnormal termination can lose all unsaved entries, not merely the final command. history -a appends newly entered lines that this session has not already appended. Saving before exit reduces that loss window, but does not promise durable storage through every system failure.

Another running shell has its own list. It needs an import such as history -n to read newly appended lines; enabling histappend alone does not make another terminal’s searches update live. history -r reads the entire file into the existing list and can introduce duplicates. history -w replaces the file with the current list and can discard other sessions’ records. These operations should not be treated as interchangeable synchronization commands.

If append and import operations are integrated into PROMPT_COMMAND, preserve existing prompt hooks and any use of the preceding command’s status. Replacing a configured hook wholesale can break other shell behavior. Concurrent sessions also do not create a reliable global execution order merely by sharing a file. Keep separate operational logs when ordering, exit status, or accountability matters.

Search, inspect, then execute

In the usual Emacs-style Readline bindings, Ctrl-R searches backward incrementally, and pressing it again finds older matches. Use an editing key to leave the search and inspect the selected line before running it; Ctrl-G cancels the search. Enter accepts the command. Ctrl-J is also a newline and must not be described as a harmless preview key. Bindings can differ in another editing mode or a customized terminal.

Inspect the hostname, directory, options, and intended target whenever reusing an old command. A command that was correct last month may address a different environment today. Prefer a distinctive search fragment and review the whole line, rather than trusting that the first matching command is the right operation.

When it breaks

Missing commands can result from filtering, retention limits, a different history file, failed saving, or an unrefreshed session. Check those causes separately. ignoredups excludes consecutive duplicates, not every duplicate in the entire list. ignoreboth combines that behavior with ignorespace; it does not produce a globally unique command archive.

A leading space excludes an entry only when the relevant setting is active. It does not remove terminal recordings, process arguments, or logs written elsewhere, so do not put credentials directly into command lines and rely on history filtering for secrecy. Diagnostic examples should use synthetic entries and a temporary history file, rather than printing someone’s real recent commands.

Check it quickly

Run this with Python 3, Bash, and standard Unix utilities. The environment points Bash to a temporary file before it starts. Only synthetic entries are inspected. The brace group avoids recording the demonstration’s own control commands after history is enabled.

import os
import subprocess
import tempfile
from pathlib import Path

script = r'''{
set -eu
set -o history
history -c
history -s 'demo original'
history -w "$HISTFILE"
printf 'first-file:\n'
cat "$HISTFILE"
history -c
history -s 'demo replacement'
history -w "$HISTFILE"
printf 'replacement-file:\n'
cat "$HISTFILE"
history -r "$HISTFILE"
printf 'memory-after-reread:\n'
history | sed 's/^[[:space:]]*[0-9][0-9]*[[:space:]]*//'
unset HISTFILE
}'''
with tempfile.TemporaryDirectory(prefix="bash-history-demo-") as directory:
 history_path = Path(directory) / "history"
 env = dict(os.environ, BASH_ENV="", HISTFILE=str(history_path), HISTSIZE="100",
 HISTFILESIZE="100", HISTCONTROL="", HISTIGNORE="",
 HISTTIMEFORMAT="")
 subprocess.run(["bash", "--noprofile", "--norc", "-c", script],
 env=env, check=True)

The first file contains demo original; after replacement it contains only demo replacement. Reading that file into a list already containing the replacement produces two identical entries in memory. This verifies overwrite and import semantics without executing the stored strings. It does not claim to test keyboard bindings or crash durability, which require their own observations.

Sources

Bash history facilities, session lists and saving to the history file, checked 2026-09-07.
Bash history builtins, append and replacement versus importing entries, checked 2026-09-07.
Readline history commands, search and command-acceptance bindings, checked 2026-09-07.

Shell word splitting turns unquoted variables into several arguments

Fri, 31 Dec 2027 00:00:00 +0000

A shell variable holds a string, but an unquoted expansion can turn that string into several command arguments. In Bash, word splitting examines expansion results using IFS as the delimiter set. This is why a pathname that works when typed with quotes can fail after being stored in a variable. Debug the arguments the receiving command actually gets, including empty ones, before blaming the filesystem.

Splitting depends on the context

With the default IFS, runs of spaces, tabs, and newlines separate fields. Leading and trailing IFS whitespace is discarded. An unquoted value containing two words therefore becomes two arguments; an empty unquoted value normally contributes none. In contrast, "$value" supplies one argument even when the string is empty. Empty and absent arguments can have completely different meanings to a program.

Splitting applies to results of unquoted parameter expansion, command substitution, and arithmetic expansion in suitable contexts. It is not a second parse of the entire command line. An ordinary assignment such as copy=$value stores the string without splitting or filename expansion. Later passing $copy unquoted to a command reintroduces both hazards. Bash conditional expressions using double brackets also have different expansion rules from ordinary command arguments.

IFS is a set of delimiter characters, not a multi-character separator or a regular expression. Non-whitespace delimiters behave differently from IFS whitespace: adjacent colons, for example, can produce an empty field. Setting IFS to an empty string disables splitting, but it does not turn an empty unquoted expansion into an explicit empty argument. Use a parser suited to the format when quoting, escaping, or structured records matter.

When it breaks

Disabling splitting does not disable the filename expansion that follows it. A variable containing a star can still become matching filenames when IFS is empty. The result can change merely because a file appeared in the working directory. Quoting the variable prevents both transformations; changing IFS alone only addresses one stage. Shell options controlling globbing are independent as well.

A scalar string is also a poor representation of an argument list. Adding quote characters inside the string does not make Bash treat those characters as shell quotation on expansion. The quotation that controls parsing must be in the command’s source. Avoid eval as a repair: it introduces another shell parse and can execute text that was previously data. For Bash commands assembled incrementally, use an array and expand it as "${args[@]}".

Some data is deliberately delimited, so splitting is not always a mistake. Make the format and delimiter explicit, keep changes to IFS local to the operation, and decide what empty fields mean. Do not use whitespace splitting to process arbitrary filenames or CSV records. These examples specifically target Bash; other shells, including zsh in its normal configuration, do not necessarily split scalar expansions the same way.

For example, a semicolon obtained from a variable does not by itself become a command separator during ordinary expansion. It remains argument data, even though splitting can still damage the surrounding value. This distinction separates incorrect argument construction from deliberately reparsing a string as code.

Check it quickly

This self-contained Bash experiment checks argument counts rather than using echo, which hides the distinction between one spaced argument and several arguments. It creates its own two matching files, tests an empty value, and checks the difference between whitespace and colon delimiters. The temporary directory is removed at exit.

bash --noprofile --norc <<'BASH'
set -e
set +f
unset GLOBIGNORE
shopt -u nullglob failglob dotglob
work=$(mktemp -d)
trap 'rm -rf -- "$work"' EXIT
cd "$work"
IFS=$' \t\n'
value='report final.md'
set -- $value
[[ $# -eq 2 ]]
set -- "$value"
[[ $# -eq 1 && $1 == 'report final.md' ]]
value=''
set -- $value
[[ $# -eq 0 ]]
set -- "$value"
[[ $# -eq 1 && $1 == '' ]]
touch a.txt 'two words.txt'
IFS=''
pattern='*.txt'
set -- $pattern
[[ $# -eq 2 ]]
set -- "$pattern"
[[ $# -eq 1 && $1 == '*.txt' ]]
IFS=:
record='red::blue'
set -- $record
[[ $# -eq 3 && $2 == '' ]]
printf 'colon field <%s>\n' "$@"
args=('report final.md' '' '*.txt')
set -- "${args[@]}"
[[ $# -eq 3 && $2 == '' && $3 == '*.txt' ]]
printf 'PASS: boundaries, empty values, globbing, delimiters\n'
BASH

Expect three colon-field lines, with an empty middle field, followed by PASS. The assertions before those lines distinguish zero arguments from one empty argument and prove that an empty IFS still permits globbing. In a failing script, put a small argument-counting function at the call boundary and print each argument separately with Bash printf’s %q format. That diagnostic shows boundaries and escaping; it does not turn a human-readable log into a safe command to execute later.

Sources

GNU Bash: Word Splitting, IFS and empty-field rules, checked 2026-09-06.
GNU Bash: Shell Expansions, splitting before filename expansion, checked 2026-09-06.
GNU Bash: Arrays, preserving a list of arguments, checked 2026-09-06.

Shell positional arguments are a numbered list

Mon, 29 Nov 2027 00:00:00 +0000

A shell script receives an ordered argument list, not a single command-line string that it must split again. Positional parameters expose that list as $1, $2, and subsequent entries; $# reports its size. A small fixed interface can use these positions directly. Optional settings and flags benefit from explicit parsing, but either design still needs to define the permitted count, empty values, and failure behavior.

Preserve the list before interpreting it

The script name in $0 is separate from the positional arguments and does not contribute to $#. With bash -c, the first argument after the command string becomes $0, which can surprise wrappers expecting it to become $1. Positions above nine require braces: ${10} means the tenth argument, whereas $10 means the first argument followed by a literal zero.

"$@" preserves one word per supplied argument, including empty arguments and values containing spaces. An unquoted expansion can split values and expand wildcard characters, while "$*" joins the list into one string. Use the quoted list when forwarding or iterating. set -- replaces the current positional list, and shift removes leading entries; neither operation changes the caller’s original list outside the relevant script or function scope.

An empty argument still occupies a position. Checking $# distinguishes an absent argument from one explicitly passed as ''. An expression such as ${1:?message} rejects both missing and empty values, which is appropriate only when the interface requires a nonempty value. Validate the count before reading required positions, then apply any separate rules about allowed contents.

Let getopts report syntax, then validate meaning

The portable getopts interface handles short options. An option character followed by a colon in the option specification takes a value; it does not automatically provide support for long names such as --user. A leading colon selects quiet error reporting: unknown options produce ?, and missing option values produce :, with the offending option available in OPTARG. The script must handle those cases explicitly.

OPTIND tracks parsing progress. Reset it to one before parsing a new argument list in the same shell, and after parsing use shift "$((OPTIND - 1))" to expose the remaining operands. -- ends option processing so a leading-hyphen filename can be an operand. A non-option also ends the ordinary option scan; do not assume options placed after operands will be rearranged automatically.

Parsing an option value does not establish that it is meaningful. An explicitly supplied empty string can satisfy the parser’s requirement for a value while violating the application’s requirement for a name. Likewise, defaults should apply only to omitted optional settings, not hide malformed input. Keep diagnostics on standard error and return a documented nonzero status before performing the requested work.

When it breaks

A common parser accepts the happy path but silently drops surplus operands. Another forgets to reset OPTIND, so a function’s first invocation works while later invocations skip options. Unquoted forwarding can produce the same outward symptom by changing the argument count before the parser sees it. Test the received list and the parsing state separately rather than adding guessed shifts until one invocation works.

The example below deliberately defines a narrow contract: optional -n NAME, optional -v, and exactly one input operand. Its name must be nonempty. The function uses Bash’s local declaration, so the complete example is Bash-specific even though the option parser itself is portable. A script targeting another shell should use that shell’s supported scoping rules instead of assuming local is standardized.

Check it quickly

Run the complete block in Bash. The first part demonstrates the tenth-position boundary and preservation of empty arguments. The parser then exercises valid input and four distinct invalid forms. All operations are local prints; no files or external commands are invoked by the demonstration function.

BASH_ENV= bash --noprofile --norc <<'BASH'
set -- one 2 3 4 5 6 7 8 9 ten
printf 'without-braces=<%s> tenth=<%s>\n' "$10" "${10}"
set -- '' 'two words'
printf 'count=%s\n' "$#"
for demo_arg in "$@"; do printf 'argument=<%s>\n' "$demo_arg"; done
demo_cli() {
 local OPTIND=1 demo_option demo_name=guest demo_verbose=no
 while getopts ':n:v' demo_option; do
 case "$demo_option" in
 n) demo_name=$OPTARG ;;
 v) demo_verbose=yes ;;
 :) printf 'missing value for -%s\n' "$OPTARG" >&2; return 2 ;;
 \?) printf 'unknown option -%s\n' "$OPTARG" >&2; return 2 ;;
 esac
 done
 shift "$((OPTIND - 1))"
 if [ "$#" -ne 1 ] || [ -z "$demo_name" ]; then
 printf 'need a nonempty name and exactly one input\n' >&2
 return 2
 fi
 printf 'name=<%s> verbose=%s input=<%s>\n' "$demo_name" "$demo_verbose" "$1"
}
demo_cli -v -n 'Jane Doe' -- '-input file'
if demo_cli -n 2>/dev/null; then exit 1; else printf 'missing=%s\n' "$?"; fi
if demo_cli -x 2>/dev/null; then exit 1; else printf 'unknown=%s\n' "$?"; fi
if demo_cli -n '' input 2>/dev/null; then exit 1; else printf 'empty=%s\n' "$?"; fi
if demo_cli one two 2>/dev/null; then exit 1; else printf 'extra=%s\n' "$?"; fi
demo_cli second
BASH

Expect one0 versus ten, followed by a count of two and two separately printed arguments. The valid invocation keeps Jane Doe and -input file intact. Missing values, unknown options, an empty name, and extra operands each return status two. The final call restores the defaults and accepts second, proving that repeated parsing starts with fresh state.

These observations verify the interface’s boundaries, not merely that a usage message exists. When extending a real command, add checks for the new option’s meaning and preserve the established treatment of quoting, empty values, and the end-of-options marker.

Sources

Bash positional parameters, numbered parameters and their function scope, checked 2026-09-07.
POSIX getopts, option syntax errors and resetting parsing state, checked 2026-09-07.

Shell parameter expansion rewrites values

Tue, 16 Nov 2027 00:00:00 +0000

Parameter expansion derives a value from a shell parameter before a command receives its arguments. It can provide a default, reject missing configuration, or remove part of a string without launching another process. This is expansion during execution, not an instruction to evaluate every variable when the script is first parsed: a function reads the current value when it runs.

Defaults distinguish missing from empty

${setting:-default} uses the default when setting is unset or empty. ${setting-default} substitutes only when it is unset, preserving an intentional empty value. The colon therefore changes configuration semantics; it is not optional punctuation. ${setting:+enabled} produces enabled only for a set, nonempty value, whereas ${setting+enabled} also accepts an empty one.

Ordinary default expansion does not assign anything. ${setting:=default} additionally stores the selected default in the variable, so subsequent reads see it. ${setting:?message} reports an unset or empty value on standard error and exits a noninteractive shell unsuccessfully. Without the colon, both operators test only whether the variable is unset. Choose according to the caller’s contract, rather than silently replacing required configuration.

Braces also separate a variable name from adjacent text. "${prefix}_suffix" appends a suffix to prefix, while "$prefix_suffix" reads a different variable altogether. This distinction matters when constructing filenames from several settings: an apparently missing value can be a name-boundary mistake rather than absent configuration. Print each component separately before investigating the resulting path, and remember that the final string can be syntactically valid even when one component came from the wrong variable.

Patterns transform strings, not files

${name#pattern} and ${name##pattern} remove the shortest and longest matching prefix. The corresponding suffix operators are % and %%. They use shell patterns, not regular expressions, and leave the original variable unchanged. If nothing matches, the result is the original string. A matching slash is just text here; these operations neither inspect directories nor resolve symbolic links.

Double-quote the complete expansion when its result must remain one argument. Quoting the result does not disable the pattern inside the braces: "${name##*/}" still removes through the last slash. These portable operators differ from Bash extensions such as substring offsets and global replacement. A script invoked as sh must not assume those extensions exist merely because the author’s interactive shell supports them.

When it breaks

An unquoted result can undergo field splitting and filename expansion. Braces delimit the variable name but do not protect argument boundaries. A value containing spaces or an asterisk can consequently turn into unrelated arguments. Also, a default expression is expanded only when selected; placing a command substitution there can execute a command on the missing-value branch. Keep defaults simple when side effects would be surprising.

Parameter expansion is not a command templating language. Text obtained from a variable is not reparsed into shell operators or quoting syntax. Construct argument lists with arrays in Bash, or explicit positional parameters in portable shell, instead of storing a command line and applying eval. set -u catches some missing values but does not validate their meaning, and pipefail has no bearing on these string operations.

Check it quickly

Run this self-contained example with Bash. It changes only variables inside a child shell and prints both the substituted values and the resulting variable state. The brackets make empty output visible.

bash --noprofile --norc <<'BASH'
unset demo_setting
printf 'unset=[%s]\n' "${demo_setting-default}"
demo_setting=
printf 'empty=[%s] colon=[%s]\n' \
 "${demo_setting-default}" "${demo_setting:-default}"
printf 'substitute=[%s] stored=[%s]\n' \
 "${demo_setting:-fallback}" "$demo_setting"
: "${demo_setting:=saved}"
printf 'assigned=[%s]\n' "$demo_setting"
demo_name='reports/weekly report.tar.gz'
printf 'base=[%s] one=[%s] all=[%s]\n' \
 "${demo_name##*/}" "${demo_name%.*}" "${demo_name%%.*}"
printf 'original=[%s]\n' "$demo_name"
show_value() { printf 'current=[%s]\n' "$demo_setting"; }
demo_setting=later
show_value
if (unset demo_setting; : "${demo_setting:?required for demo}") 2>/dev/null; then
 printf 'unexpected success\n'
else
 printf 'missing value rejected\n'
fi
BASH

Expect unset=[default], then empty=[] colon=[default]. The substitution line leaves stored=[]; the assignment line reports saved. The basename is weekly report.tar.gz, the shortest suffix removal leaves reports/weekly report.tar, and the longest leaves reports/weekly report. The original still contains its complete value.

Finally, the function prints later, proving that its variable was not frozen when the function was defined. The last line confirms rejection without terminating the outer demonstration. These observations distinguish substitution, assignment, and error handling; a successful command alone would not prove that an empty configuration value was preserved correctly.

Sources

Bash manual parameter expansion, defines expansion operators, checked 2026-06-10.
POSIX shell parameter expansion, unset versus null values and portable pattern removal, checked 2026-09-07.

Umask filters new permissions, with a default ACL exception

Sat, 09 Oct 2027 00:00:00 +0000

A process’s umask removes permission bits when creating files and directories under the ordinary mode-based creation rule. The application first supplies a requested mode; the mask restricts that request. It is neither a complete access policy nor an instruction to rewrite existing files. A directory’s default access control list changes the creation calculation, so inspecting only the process mask can give an incomplete prediction.

When it breaks

Without a default ACL, the ordinary permission result is the requested mode bitwise AND the complement of umask. For requested 0666 and mask 0022, that gives 0644. This is not arithmetic subtraction. A request for 0600 remains 0600 under the same mask, and a request that omits execute permission does not acquire it because the mask is permissive.

A restrictive umask does not repair an existing world-writable file. Opening and truncating that file changes content while preserving its existing mode. A later chmod can also widen permissions regardless of the current mask. Treating umask as a permanent upper bound on permissions therefore leaves both existing-file and subsequent-permission-change cases unaccounted for.

When the parent directory supplies a default ACL, Linux derives the new access ACL from that default and restricts it by the application’s requested mode; the process umask is not applied in the ordinary way. A shared directory can consequently produce group-accessible files even when the creator’s mask is 0077. The inherited ACL must be part of the diagnosis.

Check it quickly

Save this as mask.py and run python3 mask.py on Linux with Python 3 and setfacl installed. The temporary-file directory must support default ACLs. The recorded run used Python 3.11.2, acl 2.3.1, and a separate ext4 volume selected through TMPDIR. The initial tmpfs environment rejected default ACLs, so the complete experiment was rerun on ext4:

from pathlib import Path
from tempfile import TemporaryDirectory
import os,stat,subprocess

def create(path,requested):
 fd=os.open(path,os.O_WRONLY|os.O_CREAT|os.O_EXCL,requested);os.close(fd)
def mode(path):return stat.S_IMODE(path.stat().st_mode)
previous=os.umask(0o022)
try:
 with TemporaryDirectory(prefix='xbcatm-umask-') as directory:
 root=Path(directory)
 data=root/'data';create(data,0o666);assert mode(data)==0o644
 executable=root/'executable';create(executable,0o777);assert mode(executable)==0o755
 private=root/'private';create(private,0o600);assert mode(private)==0o600
 folder=root/'folder';folder.mkdir(mode=0o777);assert mode(folder)==0o755
 assert 0o600&~0o022==0o600 and 0o600-0o022!=0o600
 print('without default ACL: requested mode AND NOT umask; 0666 becomes 0644, 0777 becomes 0755')
 os.umask(0o077)
 strict=root/'strict';create(strict,0o666);assert mode(strict)==0o600
 existing=root/'existing';create(existing,0o666);existing.chmod(0o666)
 fd=os.open(existing,os.O_WRONLY|os.O_TRUNC);os.close(fd)
 assert mode(existing)==0o666
 print('restrictive mask leaves an existing 0666 file unchanged; chmod can widen permissions later')
 acl_folder=root/'acl';acl_folder.mkdir()
 subprocess.run(['setfacl','-d','-m','u::rwx,g::rwx,o::---',str(acl_folder)],check=True)
 inherited=acl_folder/'inherited';create(inherited,0o666)
 restricted=acl_folder/'restricted';create(restricted,0o600)
 assert mode(inherited)==0o660 and mode(restricted)==0o600
 print('with default ACL and umask 0077: request 0666 yields 0660; request 0600 still yields 0600')
 status=dict(line.split(':',1) for line in Path('/proc/self/status').read_text().splitlines() if ':' in line)
 assert int(status['Umask'].strip(),8)==0o077
 print('/proc/self/status observes this process mask without temporarily changing it')
finally:os.umask(previous)

With mask 0022 and no inherited default ACL, requesting 0666 produces a 0644 file. Requesting 0777 produces 0755 for both a regular file and a directory, while requesting 0600 still produces 0600. The fixture also checks that arithmetic subtraction would give a different result for the restrictive request, exposing that common calculation error.

After switching to mask 0077, a newly created file requested as 0666 becomes 0600. Another file is explicitly changed to 0666, then opened with truncation but without creation. Its mode stays 0666. This comparison distinguishes initial creation from later operations on an existing inode, rather than assuming every open reapplies creation policy.

Next, the fixture installs a default ACL granting the owning user and group full permissions and granting others none. Under the still-active 0077 mask, a new file requested as 0666 receives mode 0660. The inherited ACL preserves group read/write permissions despite the restrictive mask, but the application’s request excludes execute permission.

A neighboring file requested as 0600 remains 0600 under that same default ACL. The default does not invent permissions absent from the requested mode. These two requests establish both the default-ACL exception to ordinary masking and the continued role of the application’s explicit creation request.

The script reads Umask from /proc/self/status and confirms that the process mask is still 0077. It restores the original mask in finally and removes the temporary tree. If the selected filesystem cannot install the ACL, the command fails; skipping that step would leave the central exception untested.

Apply creation policy at the right layer

Umask is inherited through normal process creation and preserved across execution of another program. Set it in the actual launch path for a service or command. An unrelated terminal’s mask does not retroactively change the state of an already running process, and shell startup files matter only when the launch path reads them.

Because umask is process-wide for threads sharing the relevant filesystem state, temporarily changing it to discover its previous value can interfere with concurrent file creation. On Linux, reading the proc status field avoids that mutation. Applications needing a specific private file should request suitably restrictive permissions and verify their actual storage context.

Inspect parent-directory access, ownership, ACLs, and the resulting file permissions together. A 0660 file inside an inaccessible parent is not automatically reachable by its group, and mode bits alone do not describe all named ACL entries. The experiment proves creation results; end-to-end access requires testing the intended identity through the complete path.

Sources

umask(2), creation masks, inheritance, default ACL interaction, and proc inspection, checked 2026-09-12.
acl(5), default ACL inheritance and requested-mode permission restrictions, checked 2026-09-12.
open(2), creation modes and opening or truncating an existing file, checked 2026-09-12.

Shell aliases shrink repeated typing

Mon, 04 Oct 2027 00:00:00 +0000

An alias replaces a command word with shell text while Bash reads a command. It is useful for personal shortcuts such as alias ll='ls -l', but it is not an executable and has no independent argument scope. Noninteractive Bash disables alias expansion by default; a script can explicitly enable it. Understanding that distinction explains why a shortcut works at a prompt but disappears in automation.

Replacement happens when input is read

An unquoted word in command position is eligible for alias expansion. With alias ll='ls -l', ll 'two words' becomes a command whose final argument still contains the space. Aliases do not inherently destroy quoting on arguments supplied by the caller. They simply cannot refer to their own $1 or rearrange a private argument list as functions can.

The replacement can contain shell syntax, including pipelines or several commands, so aliases are not technically limited to one executable. That freedom also makes their behavior harder to inspect. Bash expands the first word of the replacement again, except when it is the alias already being expanded. Consequently, alias ls='ls -F' does not recurse forever. A trailing blank in an alias value has another special effect: the following command word is also checked for alias expansion.

Quoting the definition controls another timing boundary. Single quotes preserve dollar signs for later interpretation in the replacement text; double quotes can expand variables immediately while the alias is being defined. A shortcut meant to follow a changing directory variable can therefore retain an old value. Inspect the stored definition, not just the line originally typed, when diagnosing that discrepancy.

Scope and timing are different questions

Aliases belong to the current shell; they are not environment variables exported to a separately launched Bash process. A subshell created with parentheses inherits the shell state, which is a different operation. Startup files can define the same alias again, but that is configuration being loaded, not an alias travelling through the environment.

In Bash, shopt -s expand_aliases enables expansion in a noninteractive shell. Definitions must still precede the input that uses them. Bash reads a complete line or compound command before executing it, so defining an alias and invoking it later on the same line does not activate that new definition in time. The same issue applies inside a function body being parsed.

When it breaks

A function can capture an alias expansion when its definition is read. Replacing that alias afterward does not rewrite the already parsed function. This surprises users who expect every call to consult the latest alias table. Define functions directly when their behavior should be explicit, and use quoted "$@" to forward arguments without losing empty values or spaces.

Another failure is mistaking a shortcut for a command available to another program. A process launcher does not consult your interactive alias table. Diagnose the current shell with type name and inspect a specific definition with alias name; remove it with unalias name. Quoting or backslash-escaping the command word suppresses alias expansion, but functions or builtins can still affect subsequent lookup. An explicit executable path selects that file.

Check it quickly

This Bash experiment uses only diagnostic names and builtins. It intentionally compares disabled expansion, enabled expansion, same-line definition, and a function parsed before an alias changes. Expected failures are captured immediately so a later successful print cannot hide their status.

bash --noprofile --norc <<'BASH'
shopt -u expand_aliases
alias demo_alias='printf "alias=<%s>\n"'
demo_alias hidden 2>/dev/null
printf 'disabled=%s\n' "$?"
shopt -s expand_aliases
demo_alias 'two words' ''
alias demo_late='printf "late\n"'; demo_late 2>/dev/null
printf 'same-line=%s\n' "$?"
demo_late
alias demo_version='printf "old\n"'
demo_function() { demo_version; }
alias demo_version='printf "new\n"'
demo_function
demo_version
unalias demo_alias
if command -v demo_alias >/dev/null 2>&1; then
 printf 'unexpected command\n'
else
 printf 'alias removed\n'
fi
BASH

Expect status 127 while expansion is disabled, followed by alias=<two words> and alias=<> after enabling it. The same-line call also returns 127; the next line prints late. The function then prints old, while a direct invocation prints new. Finally, lookup confirms removal.

These results establish the actual boundaries: argument quoting can survive a simple alias, noninteractive expansion is configurable, and read-time substitution can freeze behavior inside a function. For shared scripts, put reusable logic in a function or executable that the script defines or loads explicitly. Keep aliases as visible conveniences for the shell session in which they were configured.

Sources

Bash reference manual: aliases, the maintainer-hosted manual on expansion timing and noninteractive behavior, checked 2026-09-07.
POSIX alias substitution, command-word substitution and quoting rules, checked 2026-09-07.

Redirection reorders the streams

Wed, 29 Sep 2027 00:00:00 +0000

Redirection changes a command’s file descriptors before the command executes. The shell processes redirections from left to right, opening or duplicating a descriptor as it reaches each operation. Descriptors 0, 1, and 2 conventionally represent standard input, standard output, and standard error. Reading this sequence as concrete changes to those handles explains both misplaced diagnostics and files that become empty before their contents can be read.

Opening a file is already a side effect

>output opens a file for writing and normally truncates an existing regular file. >>output opens it for appending. <input opens a file for reading. These actions belong to the shell, not to the program named by the command. If opening a required target fails, the command is not executed; successful earlier redirections can still have created or truncated other files.

Consequently, transforming a file with sed expression input >input destroys the original before sed can read it. Opening input first with <input does not rescue the data if a later redirection truncates the same underlying file. Write to a separate temporary file, check the transformation’s status and result, and only then perform a deliberate replacement appropriate to the file’s ownership and filesystem.

Duplication captures the current destination

>log 2>&1 first sends descriptor 1 to the log, then makes descriptor 2 refer to that same open destination. 2>&1 >log first duplicates the original standard output onto descriptor 2, then changes only descriptor 1. Standard error therefore remains at the original destination, such as a terminal or a capturing pipe. Duplication copies a descriptor reference, not file contents, and it does not create a live connection between descriptor numbers.

Bash’s &>log is shorthand for redirecting both streams, but >log 2>&1 also works in portable shell scripts. Opening the same filename twice with >log 2>log is not equivalent: the two opens have independent offsets and can overwrite one another’s output. Even when descriptors share one destination, application buffering can affect the order in which messages become visible.

Pipelines connect standard output to the next stage before command-specific redirections are applied. In producer >file | consumer, the producer’s output consequently goes to the file, leaving the consumer without that data. Conversely, producer 2>&1 | consumer sends diagnostics through the pipe too. When the consumer expects machine-readable records, merging human-readable errors into that stream can corrupt otherwise valid input.

When it breaks

Quote variable filenames so spaces do not turn a target into multiple words. Keep the descriptor number adjacent to its operator: 2>errors redirects standard error, while 2 >errors supplies an ordinary argument containing 2 and redirects standard output. A misplaced space can therefore change both program input and output routing.

Bash’s set -C enables noclobber, rejecting ordinary output redirection to an existing regular file. It is useful protection against accidental replacement, not a backup system or a universal guarantee about every file type. >| explicitly overrides it. Also distinguish a command’s temporary redirections from exec >log, which changes the current shell’s descriptors and can redirect every subsequent command. Local tests should not unexpectedly silence the surrounding session.

Check it quickly

Run the following in Bash with standard Unix utilities. Only freshly created temporary files are truncated or removed. The output compares both orderings, demonstrates same-file truncation, and checks that a failed redirection prevents a function body from running.

bash --noprofile --norc <<'BASH'
set -eu
demo_dir=$(mktemp -d)
trap 'rm -f "$demo_dir/both" "$demo_dir/out" "$demo_dir/input"; rmdir "$demo_dir"' EXIT
emit() { printf 'out\n'; printf 'err\n' >&2; }
emit > "$demo_dir/both" 2>&1
demo_captured=$(emit 2>&1 > "$demo_dir/out")
printf 'both:\n'
cat "$demo_dir/both"
printf 'out-file=[%s] captured=[%s]\n' \
 "$(cat "$demo_dir/out")" "$demo_captured"
printf 'seed\n' > "$demo_dir/input"
sed 's/seed/replaced/' "$demo_dir/input" > "$demo_dir/input"
if [ ! -s "$demo_dir/input" ]; then printf 'input truncated\n'; fi
if (set -C; emit > "$demo_dir/both") 2>/dev/null; then
 printf 'unexpected overwrite\n'
else
 printf 'noclobber rejected overwrite\n'
fi
demo_ran=no
mark_run() { demo_ran=yes; }
if mark_run 2>/dev/null > "$demo_dir/missing/output"; then
 printf 'unexpected redirection\n'
else
 printf 'function-ran=%s\n' "$demo_ran"
fi
BASH

The combined file prints out and err. Reversed ordering leaves only out in the output file and captures err separately. The transformation reports an empty input because truncation preceded execution. The remaining lines confirm that noclobber rejected replacement and the failed open left function-ran=no.

These checks observe file contents and whether the command actually ran, rather than relying on a successful final print. In a real script, retain the producer’s exit status alongside its logs: a perfectly routed error message does not turn a failed operation into success. Keeping output routing and operation status separate makes recovery decisions reliable.

Sources

Bash reference manual: redirections, left-to-right descriptor changes and noclobber behavior, checked 2026-09-07.
POSIX shell redirection, portable redirection operators and file-opening semantics, checked 2026-09-07.

Shell pipes stream between processes

Tue, 28 Sep 2027 00:00:00 +0000

A shell pipeline connects one command’s standard output to the next command’s standard input. The commands can run concurrently, so the producer need not finish before the consumer starts. This supports incremental processing, but the pipe itself does not guarantee that either program processes data incrementally. Buffering, early termination, and the status of each stage determine whether the complete operation does what you intended.

A byte stream with finite capacity

A pipe transports bytes rather than records. A reader is not promised one read per line or one read per producer write. Programs must implement any framing they need. Standard error normally remains separate, which is why an upstream diagnostic can appear on the terminal without entering the downstream filter. Decide explicitly whether a consumer should receive diagnostics as data.

The kernel provides finite buffering. A blocking writer waits when the pipe fills, and a reader waits when the pipe is empty while writers remain open. This backpressure limits how far a producer can advance through that particular pipe. Capacity depends on the operating system and configuration; it is not universally sixty-four kibibytes. Applications can still accumulate arbitrarily large internal data structures, so a pipeline alone does not bound total memory.

User-space buffering adds another delay. A program that flushes every line to a terminal may buffer larger chunks when stdout is a pipe. An apparently idle consumer may therefore be waiting for data still buffered in the producer. Check the producer’s documented streaming and flush controls before changing kernel limits or adding arbitrary sleeps. Some transformations, such as a complete sort, inherently need more input before producing useful output.

When it breaks

A reader sees end-of-file only after every descriptor referring to the write end is closed. A child that inherited an unused write descriptor can keep a consumer waiting even after the apparent producer exited. In the other direction, writing after all read ends are closed generates SIGPIPE, or yields an EPIPE error when the signal is ignored. A consumer that deliberately stops early can therefore cause an otherwise healthy producer to terminate unsuccessfully.

By default, Bash returns the last stage’s status. An upstream failure followed by a successful cat can look successful overall. With pipefail, the aggregate result is the rightmost nonzero stage status, not the first failure in time or the leftmost failing command. The PIPESTATUS array retains individual stage results briefly. Capture it immediately: even an assignment or printf can replace the observation.

Most Bash pipeline stages run in subshell environments. An assignment in a loop on the right side of a pipe normally does not update the caller’s variable. Bash’s lastpipe option can alter the final stage’s execution when job control is inactive, so state assumptions need an explicit shell configuration. A redirected loop can avoid a pipeline when the caller must retain the loop’s state.

Finally, a foreground Bash pipeline waits for its stages to terminate. It does not return merely because the consumer read its first line. A producer that catches a broken pipe and continues unrelated work can delay completion. Treat a pipeline as several processes with connected descriptors and separate outcomes, rather than one command that necessarily succeeds or stops as a unit.

Check it quickly

Run the following Bash block with cat, yes, and head available. It compares default and pipefail statuses using a producer that deliberately exits seven. It then demonstrates two failing stages and an early-closing consumer. Errexit is disabled only while collecting expected nonzero results, then restored before assertions.

bash --noprofile --norc <<'BASH'
set -e
set +o pipefail
set +e
(printf 'partial\n'; exit 7) | cat >/dev/null
plain=("$?" "${PIPESTATUS[@]}")
set -e
[[ ${plain[*]} == '0 7 0' ]]
set -o pipefail
set +e
(printf 'partial\n'; exit 7) | cat >/dev/null
strict=("$?" "${PIPESTATUS[@]}")
set -e
[[ ${strict[*]} == '7 7 0' ]]
set +e
(exit 7) | (exit 4)
multiple=("$?" "${PIPESTATUS[@]}")
set -e
[[ ${multiple[*]} == '4 7 4' ]]
set +e
yes | head -n 1 >/dev/null
early=("$?" "${PIPESTATUS[@]}")
set -e
[[ ${early[0]} -ne 0 && ${early[1]} -ne 0 && ${early[2]} -eq 0 ]]
printf 'default: %s\npipefail: %s\nrightmost: %s\nearly close: %s\n' \
 "${plain[*]}" "${strict[*]}" "${multiple[*]}" "${early[*]}"
printf 'PASS: aggregate and individual stage outcomes\n'
BASH

Each reported array starts with the aggregate status, followed by the stages in source order. Expect 0 7 0, 7 7 0, and 4 7 4 for the first three. The final consumer succeeds while yes returns nonzero; the test deliberately does not require a platform-specific signal number. A production pipeline must distinguish this intentional early closure from lost required output. Measure throughput and memory separately; these status assertions do not measure buffering performance.

Sources

GNU Bash: Pipelines, process execution and aggregate status rules, checked 2026-09-06.
Linux man-pages: pipe(7), byte streams, descriptor lifetime, capacity, and SIGPIPE, checked 2026-09-06.
GNU Bash: Special Parameters, the immediately preceding command’s status, checked 2026-09-06.

Job control moves terminal foreground ownership between groups

Mon, 27 Sep 2027 00:00:00 +0000

Interactive job control lets a shell manage process groups that share a controlling terminal. The terminal has one foreground process group at a time, while other jobs can run or remain stopped in the background. Foreground ownership, running state, and the shell’s job table are distinct. A background job is not automatically suspended, and a stopped job has not necessarily terminated.

When it breaks

Typing a configured interrupt or suspend character causes the terminal driver to signal the foreground group when terminal signal processing is enabled. It does not simply signal whichever individual process last printed something. Remapped control characters, altered terminal modes, or a program’s signal handlers can change the observed behavior, so key labels alone do not establish a universal result.

A normal background job attempting to read its controlling terminal is stopped by SIGTTIN. Moving it to the background does not hand it an independent keyboard stream. Output is different: background writes are normally allowed, with additional behavior controlled by terminal settings such as TOSTOP. Background execution therefore does not imply complete separation from the terminal.

Job specifications such as %1 belong to a particular shell’s job table; they are not global process identifiers. Another terminal or a noninteractive shell cannot be assumed to manage that same job using the same number. Pipelines and background commands also depend on whether job control is enabled in the actual shell invocation.

Check it quickly

Save the script as jobcontrol.py and run python3 jobcontrol.py on Linux with Bash and Python installed. The recorded run used Linux 6.12.76, Bash 5.2.15, and Python 3.11.2. It creates its own pseudo-terminal and interactive Bash, so it does not send control characters to the terminal from which you launch it:

from pathlib import Path
import os,pty,re,select,signal,termios,time

pid,master=pty.fork()
if pid==0:
 attributes=termios.tcgetattr(0);attributes[3]&=~termios.ECHO;attributes[3]|=termios.ISIG|termios.ICANON
 attributes[6][termios.VINTR]=b'\x03';attributes[6][termios.VSUSP]=b'\x1a';attributes[6][termios.VEOF]=b'\x04'
 termios.tcsetattr(0,termios.TCSANOW,attributes)
 os.execve('/bin/bash',['bash','--noprofile','--norc','-i'],{'PATH':'/usr/bin:/bin','TERM':'dumb','LC_ALL':'C','PS1':'XB-PROMPT> ','HISTFILE':'/dev/null'})
known_groups={pid};pending=b''
def until_prompt():
 global pending
 deadline=time.monotonic()+5
 while b'XB-PROMPT> ' not in pending:
 remaining=deadline-time.monotonic();assert remaining>0,pending
 ready,_,_=select.select([master],[],[],remaining);assert ready,pending
 chunk=os.read(master,65536);assert chunk,'PTY closed before prompt';pending+=chunk
 output,pending=pending.split(b'XB-PROMPT> ',1)
 return output.decode(errors='replace')
def command(text):os.write(master,text.encode()+b'\n');return until_prompt()
def wait_for(predicate):
 deadline=time.monotonic()+5
 while not predicate():
 assert time.monotonic()<deadline,'terminal state did not change';time.sleep(0.01)
def state(process):
 try:return (Path('/proc')/str(process)/'stat').read_text().rsplit(') ',1)[1].split()[0]
 except FileNotFoundError:return None
try:
 until_prompt();assert os.tcgetpgrp(master)==pid
 os.write(master,b'sleep 60 | cat\n')
 wait_for(lambda:os.tcgetpgrp(master)!=pid)
 group=os.tcgetpgrp(master);known_groups.add(group)
 os.write(master,b'\x1a');output=until_prompt()
 assert 'Stopped' in output and os.tcgetpgrp(master)==pid,output
 assert 'Stopped' in command('jobs -l')
 print('Ctrl-Z stops the foreground pipeline and returns the terminal to the interactive shell')
 command('bg %1');assert os.tcgetpgrp(master)==pid
 os.write(master,b'fg %1\n');wait_for(lambda:os.tcgetpgrp(master)==group)
 os.write(master,b'\x03');until_prompt()
 assert 'RESULT:130' in command("printf 'RESULT:%s\\n' \"$?\"")
 print('bg resumes without foreground ownership; fg restores ownership; Ctrl-C gives this pipeline status 130')
 output=command("cat & printf 'BG:%s\\n' \"$!\"")
 background=int(re.search(r'BG:(\d+)',output)[1]);known_groups.add(background)
 wait_for(lambda:state(background)=='T')
 assert os.tcgetpgrp(master)==pid
 assert 'Stopped (tty input)' in command('jobs -l')
 print('a background reader is stopped by terminal input rules, rather than receiving the shell keyboard stream')
 os.write(master,b'fg %+\n');wait_for(lambda:os.tcgetpgrp(master)==background)
 os.write(master,b'hello\n\x04');output=until_prompt();assert 'hello' in output,output
 assert 'RESULT:0' in command("printf 'RESULT:%s\\n' \"$?\"")
 print('foregrounding that reader lets it read; EOF ends it normally; all jobs are reaped')
 assert not command('jobs -p').strip()
 os.write(master,b'exit\n');waited,status=os.waitpid(pid,0);assert waited==pid and os.WIFEXITED(status)
 pid=None
finally:
 if pid is not None:
 for group in known_groups:
 try:os.killpg(group,signal.SIGKILL)
 except ProcessLookupError:pass
 os.waitpid(pid,0)
 os.close(master)

The fixture enables terminal signal processing and canonical input, explicitly assigns interrupt, suspend, and EOF characters, and disables input echo. It starts Bash without user startup files and uses a recognizable prompt. These choices make the experiment reproducible without relying on a user’s aliases, prompt commands, or customized terminal key bindings.

Bash first runs sleep 60 | cat in the foreground. The controller observes the terminal’s foreground PGID change from Bash to the pipeline. Sending the suspend character stops the job, produces a Stopped report, and returns foreground ownership to Bash. jobs -l confirms that the shell still knows the stopped job.

bg %1 resumes the pipeline while Bash retains the terminal. fg %1 then gives foreground ownership back to the pipeline. Sending the interrupt character ends this default-behavior pipeline, and Bash reports status 130. This is an observed Bash status for this command, not a promise that every application must exit on INT or return the same value.

The script next launches a background cat, records its PID, and waits for a stopped process state. Bash reports Stopped (tty input). This is a terminal-input restriction, not completion and not evidence that the reader consumed the shell’s next command. The shell remains the terminal’s foreground group throughout this background attempt.

Foregrounding that reader lets it receive hello. An EOF character at an empty canonical input line allows it to finish normally, after which Bash reports zero and its job table is empty. The controller then exits Bash and reaps it. Failure cleanup is limited to the isolated groups created by the experiment.

Choose the intended lifetime and input source

Use bg when a stopped job can proceed without interactive terminal input. Use fg when it needs the terminal again. Redirecting input to a suitable file or pipe can let background work run independently of keyboard input, but it does not automatically detach the process from its session or define what happens when the login ends.

Use a service manager for workloads whose lifetime must outlive an interactive session and whose restart, logging, and resource policies must be explicit. A shell job table is useful for current interactive work; it is not durable service state. Disowning a job or changing hangup handling also answers narrower questions than full service supervision.

When a job seems frozen, inspect whether it is stopped, waiting for data, or still computing before sending termination signals. Correlate the job specification, PID, PGID, and terminal foreground group. This prevents confusing a legitimate terminal-input stop with a crashed process and helps restore the intended interaction without unnecessarily discarding the work.

Sources

Bash job-control basics, foreground groups, terminal input, suspension, and job states, checked 2026-09-12.
Bash job-control builtins, jobs, bg, fg, and shell-local job specifications, checked 2026-09-12.
termios(3), terminal control characters and signal generation, checked 2026-09-12.
tcgetpgrp(3), reading and selecting the terminal foreground process group, checked 2026-09-12.

Environment variables are a per-process thing

Sat, 25 Sep 2027 00:00:00 +0000

An environment is a collection of name-value strings supplied to a program when it starts. A child normally receives the environment selected by its parent; changing that child’s copy does not rewrite the parent’s or a sibling’s copy. This is a useful configuration boundary, but it is not a promise that the command has no side effects. The program can still modify shared files, databases, or other resources using those settings.

Export selects values for another program

A shell variable and an environment entry are related but distinct. Assigning DEMO_SETTING=local creates or updates a shell parameter. export DEMO_SETTING marks it for inclusion when the shell launches external commands. A new Bash process normally cannot see an unexported shell variable, even though the parent can print it. Merely placing an assignment in a configuration file does not load that file into every shell.

A value inherited through the environment is already marked for export by Bash. Changing its value retains that attribute, so a later grandchild can inherit the changed value without another export statement. unset removes the variable; Bash’s export -n removes its export attribute while retaining the shell value. The relevant question is which environment the immediate launcher supplied, not whether every ancestor repeated an export command.

A subshell is not a freshly executed shell

Parenthesized command groups and command substitution run in a subshell environment copied from the current shell. They can see ordinary shell variables that were never exported. Their assignments still do not flow back into the outer shell. This differs from executing a separate shell program, which receives exported entries rather than a complete copy of the parent’s shell parameter table.

Sourcing a file with . runs its commands in the current shell. Its assignments can therefore change the caller directly; it is not an exception to process isolation because no separate process is returning those changes. A sourced file is executable shell code, not passive configuration. Only source a file whose contents you intend to execute in that context.

Per-command settings have a defined lifetime

A prefix such as DEMO_SETTING=once external-command supplies a value for that invocation without permanently changing the surrounding shell’s value. This statement concerns an external command; assignment behavior around special builtins and functions has additional shell-specific rules. Do not generalize it into a claim that every command-looking construct creates an isolated process.

At the operating system interface, execve takes an explicit environment array and replaces the current process image. It does not itself create a new process. A launcher can preserve, filter, or replace the environment, which explains why privilege boundaries, service managers, and container configuration may produce values different from an interactive terminal. Process ancestry alone is insufficient to establish the actual settings delivered to an application.

When it breaks

Editing a terminal’s environment does not update an already running service. Likewise, changing an environment file has no effect until the relevant launcher rereads it and starts the process, unless the application provides its own reload mechanism. Check the configuration path used by that service and verify the resulting behavior in the process that actually handles requests.

Treat missing and empty values separately, because applications may assign them different meanings. Environment strings cannot contain an embedded NUL, and platforms limit the combined argument and environment size, so they are unsuitable for arbitrary binary payloads or unbounded documents. Inspect only the specific nonsecret keys needed for diagnosis; dumping an entire environment can expose credentials inherited by unrelated tools.

Check it quickly

Run this Bash example. It prints only a dedicated demonstration variable, uses no external configuration file, and leaves the surrounding terminal unchanged. The small here-document passed to . contains the complete trusted configuration used for the sourcing test.

BASH_ENV= bash --noprofile --norc <<'BASH'
unset DEMO_SETTING
DEMO_SETTING=local
printf 'shell=%s\n' "$DEMO_SETTING"
bash --noprofile --norc -c 'printf "unexported-child=%s\n" "${DEMO_SETTING-unset}"'
(printf 'subshell=%s\n' "$DEMO_SETTING")
export DEMO_SETTING
bash --noprofile --norc <<'CHILD'
printf 'exported-child=%s\n' "$DEMO_SETTING"
DEMO_SETTING=child
bash --noprofile --norc -c 'printf "grandchild=%s\n" "$DEMO_SETTING"'
CHILD
printf 'parent-after-child=%s\n' "$DEMO_SETTING"
DEMO_SETTING=once bash --noprofile --norc -c 'printf "one-command=%s\n" "$DEMO_SETTING"'
printf 'parent-after-command=%s\n' "$DEMO_SETTING"
. /dev/stdin <<'CONFIG'
DEMO_SETTING=sourced
CONFIG
printf 'parent-after-source=%s\n' "$DEMO_SETTING"
BASH

The unexported child prints unset, while the parenthesized subshell sees local. After export, the new child sees local, changes its own copy, and passes child to its grandchild. The outer shell remains local. The one-command override prints once, and the following parent check is still local.

Finally, sourcing changes that outer child shell’s value to sourced. Together these observations distinguish shell parameters, exported entries, subshell copies, per-command overrides, and execution in the current shell. They establish variable scope, not the absence of application side effects or the correctness of a service’s deployment configuration.

Sources

Bash execution environment, exported entries versus the state copied into subshells, checked 2026-09-07.
Bash environment, export attributes and per-command assignments, checked 2026-09-07.
POSIX exec functions, process-image replacement and explicit environment arrays, checked 2026-09-07.

Bash globbing expands before the command runs

Wed, 08 Sep 2027 00:00:00 +0000

A wildcard in a Bash command usually becomes a list of pathnames before the target program starts. That makes *.txt convenient, but it also makes the command depend on the current directory and shell options. The program receives arguments, without information saying which ones came from a wildcard. Decide whether you intend to pass matching files or a pattern for the program to interpret.

Match first, then preserve the arguments

Bash performs word splitting before filename expansion. An unquoted *, ?, or bracket expression can therefore produce several arguments. A matching filename containing spaces remains one argument: Bash does not run another word-splitting pass over the filenames it just found. The common loss of spaces happens later when a loop expands its variable without quotes. Use "$file" when passing each matched pathname onward.

Quote a pattern when its recipient needs the pattern itself. For example, find . -name '*.txt' gives the matching expression to find; leaving it unquoted lets Bash expand it against the current directory first. A quoted variable containing an asterisk also stays literal. An unquoted variable containing an asterisk can trigger pathname expansion, even though the star was not written directly in the command.

A pattern operates on directory entries, not a promised collection of regular files. A directory named archive.txt also matches *.txt. Use a file-type check when that distinction matters. Ordinary stars do not cross slashes, and leading dots require explicit matching unless dotglob is enabled. Recursive traversal needs its own deliberate approach; plain * does not search the whole tree.

The environment can also change which names qualify. In Bash, setting GLOBIGNORE to a nonempty value filters matching names and enables dotglob as a side effect. A script inherited from an interactive session may therefore see hidden files unexpectedly. The fixture below clears that variable and selects its options explicitly so its assertions describe a reproducible configuration.

When it breaks

By default, an unmatched pattern stays as literal text. A loop over *.png can consequently run once with a nonexistent filename. With nullglob enabled, the pattern disappears instead. This avoids that literal but introduces another risk: a command receiving no file arguments may read standard input, or apply its own default target. Neither nounset nor pipefail checks that a glob found files.

For optional inputs, collect matches in a Bash array with nullglob and test its element count before invoking the consumer. For required matches, failglob rejects an unmatched expansion before the command runs. Keep option changes inside a subshell when callers should retain their original settings. Do not assume a script’s behavior matches an interactive shell whose startup files changed those options.

A filename beginning with a hyphen may be interpreted as an option by the receiving program. Expanding ./*.txt prefixes such names with a directory component; use the program’s documented -- separator where supported as well. Quoting preserves argument boundaries but does not change option parsing. Finally, enumeration and use are separate events: files can disappear between them, so a successful match is not proof that a later read will succeed.

Check it quickly

Run the following block with Bash and the usual temporary-directory tools. It creates an isolated directory, checks literal and expanded arguments, exercises both no-match policies, and removes only its own fixture. It does not require any preexisting text files.

bash --noprofile --norc <<'BASH'
set -e
export LC_ALL=C
set +f
unset GLOBIGNORE
shopt -u nullglob failglob dotglob
work=$(mktemp -d)
trap 'rm -rf -- "$work"' EXIT
cd "$work"
touch -- a.txt 'two words.txt' .hidden.txt -option.txt
files=(./*.txt)
[[ ${#files[@]} -eq 3 ]]
[[ ${files[2]} == './two words.txt' ]]
printf 'match <%s>\n' "${files[@]}"
literal=('*.txt')
[[ ${literal[0]} == '*.txt' ]]
missing=(./*.missing)
[[ ${missing[0]} == './*.missing' ]]
shopt -s nullglob
missing=(./*.missing)
[[ ${#missing[@]} -eq 0 ]]
if (shopt -s failglob; printf '%s\n' ./*.missing) 2>/dev/null; then
 printf 'unexpected match\n' >&2
 exit 1
fi
shopt -s dotglob
files=(./*.txt)
[[ ${#files[@]} -eq 4 ]]
printf 'PASS: spaces, literal, no-match policies, hidden file\n'
BASH

Expect three initial match lines, with the spaced filename on one line, followed by the PASS message. The hidden file appears only in the final array after dotglob is enabled. The failing subshell is intentional and must not print an expanded filename. These assertions verify Bash expansion and argument preservation; they do not establish how an arbitrary downstream tool handles missing operands, directories, or options. Check that tool’s contract before replacing the harmless printf with a real operation.

Sources

GNU Bash: Filename Expansion, matching rules and no-match options, checked 2026-09-06.
GNU Bash: Shell Expansions, ordering and changes to argument count, checked 2026-09-06.
GNU Bash: Arrays, collecting matches and preserving elements, checked 2026-09-06.

A bare command the shell cannot find

Thu, 20 May 2027 00:00:00 +0000

“Command not found” identifies a lookup failure, but lookup does not always mean walking every directory in PATH. In ordinary Bash, a command word without a slash can resolve to a function, builtin, cached executable path, or a newly searched executable. An alias may already have changed the command while the input was read. Inspect the shell that actually reported the failure before reinstalling a tool that may already exist.

Know which lookup layer answered

After expansion, Bash checks functions and then builtins before searching for an external command. type name describes the current resolution, and type -a name exposes additional definitions or candidates. command -v name is useful for testing availability in that shell, but its result need not be a filesystem path. It can identify a function or builtin, so do not blindly treat the output as a file to copy.

For external commands, directories in PATH are searched in order. An earlier executable can shadow a newer version later in the list. Bash also caches successful paths; hash -t name inspects a cached entry and hash -r clears the table. A changed file at an already cached location and a different path choice are separate issues. Starting a new terminal can hide this distinction by resetting shell state.

A slash selects a path directly

Any slash in the command word bypasses the external PATH search. ./tool addresses a file in the current directory; /opt/example/bin/tool addresses an absolute location. A bare tool does not automatically search the current directory. Empty or relative entries in PATH can make it do so, which allows the current working directory to change the selected executable.

Use explicit, trusted directories when assembling a service’s environment. A working interactive terminal does not establish that cron, a service manager, or another user has the same path or startup files. Compare their actual environments and working directories. Changing a login configuration file will not update an already running process; apply the intended environment to the process that launches the command.

When it breaks

Bash normally reports 127 when a command cannot be found and 126 when a located command cannot be executed. These values guide investigation, but they are not a complete diagnosis: an existing script can fail because the interpreter named by its shebang is missing. Read the diagnostic and inspect the selected file’s permissions and interpreter instead of repeatedly appending directories.

Do not “fix” lookup by adding writable project directories ahead of trusted tools or by using administrator privileges indiscriminately. First establish whether a function, an alias, or a cached location is responsible. command name bypasses a same-named function in Bash; an explicit executable path bypasses path selection. Neither makes the selected program itself trustworthy or repairs its missing dependencies.

Check it quickly

This Bash example creates two disposable executables with the same name. Its temporary directories are the only additions to PATH, and all changes stay inside the child shell. Cleanup names each file explicitly. No installed executable is modified.

Setup uses errexit to stop if fixture creation fails, then disables it before deliberately testing failures. On Bash 3.2.57, used to check this example, keeping that option enabled makes these execution-failure branches report 1 instead of the ordinary 126 and 127. Recording the shell version and options is therefore part of interpreting an unexpected status, not merely a reproducibility detail.

bash --noprofile --norc <<'BASH'
set -eu
demo_dir=$(mktemp -d)
trap 'rm -f "$demo_dir/one/demo-tool" "$demo_dir/two/demo-tool" "$demo_dir/blocked"; rmdir "$demo_dir/one" "$demo_dir/two" "$demo_dir"' EXIT
mkdir "$demo_dir/one" "$demo_dir/two"
printf '#!/bin/sh\nprintf "one\\n"\n' > "$demo_dir/one/demo-tool"
printf '#!/bin/sh\nprintf "two\\n"\n' > "$demo_dir/two/demo-tool"
chmod +x "$demo_dir/one/demo-tool" "$demo_dir/two/demo-tool"
PATH="$demo_dir/one:$demo_dir/two:$PATH"
demo-tool
hash -p "$demo_dir/two/demo-tool" demo-tool
demo-tool
hash -r
demo-tool
demo-tool() { printf 'function\n'; }
demo-tool
command demo-tool
unset -f demo-tool
"$demo_dir/two/demo-tool"
: > "$demo_dir/blocked"
chmod 600 "$demo_dir/blocked"
set +e
if "$demo_dir/blocked" 2>/dev/null; then
 printf 'unexpected execution\n'
else
 printf 'not-executable=%s\n' "$?"
fi
if "$demo_dir/missing" 2>/dev/null; then
 printf 'unexpected file\n'
else
 printf 'missing=%s\n' "$?"
fi
BASH

The first three lines should be one, two, one: normal search, an explicitly installed cache entry, and a fresh search after clearing it. Next come function, one, and two, distinguishing function dispatch, function bypass, and an explicit path. Finally, the nonexecutable file returns 126 and the absent path returns 127.

This proves selection behavior with controlled files. It does not reproduce every operating system loader error or service environment. For a real incident, record the resolved command and its version in the failing environment, then verify the corrected invocation there. A successful lookup in an unrelated terminal is insufficient evidence that the original failure is repaired.

Sources

POSIX shell command search, command search rules and the not-found exit status, checked 2026-06-01.
Bash reference manual: command search and execution, function and builtin precedence plus cached executable paths, checked 2026-09-07.

$@ and friends give a function its whole argument list

Fri, 16 Apr 2027 00:00:00 +0000

A wrapper should pass the arguments it received without changing their boundaries. In Bash, "$@" does that when used as command arguments: each positional parameter becomes a separate quoted word. This matters for empty values, spaces, newlines, and literal wildcard characters. A command that happens to work with two simple filenames can still be broken if its wrapper reconstructs the list as a single string.

A list is different from joined text

The positional parameters are the arguments of the current script or function. $# reports their count, including arguments whose value is an empty string. "$1" selects the first argument, while "${10}" selects the tenth; braces distinguish that reference from the first argument followed by a zero. $0 identifies the invoked shell or script and is not an extra element of "$@".

At a normal command boundary, "$@" preserves each parameter as its own word. With no positional parameters, it produces no arguments. Quoted "$*" instead produces one string, joining parameter values with the first character of IFS. If IFS is unset, the join uses spaces; if it is empty, the join inserts no separator. The original spaces inside values remain, but the original boundaries cannot generally be recovered.

Unquoted $@ is not an equivalent shorthand. Its values can undergo word splitting and filename expansion. A literal star supplied by the caller may suddenly match files in the wrapper’s directory. Adding quote characters to a joined string does not restore the lost structure. In Bash, save a list with args=("$@") and forward it with "${args[@]}" when it must survive later changes to the positional parameters.

When it breaks

A function receives its own positional parameters while it runs. Calling it with arguments replaces the visible list for that call, and returning restores the caller’s list. Using set or shift inside the function changes that function’s list. This does not mean every other shell setting is local to the function: changing IFS without a local declaration, for example, can affect the caller. Limit variable changes deliberately.

Shift removes leading positional parameters and renumbers the remainder. Check that enough parameters remain before consuming an option and its value; shifting beyond the available count fails. A parser that only checks for a nonzero count can still mishandle an option requiring a second argument. Preserve the original list in an array if diagnostics or later forwarding require values already consumed by parsing.

Quoting also cannot prevent the receiving command from interpreting an argument as an option. A filename equal to --help remains one intact argument under "$@", but a tool might treat it as a help request. Use the tool’s documented option terminator or a suitable pathname prefix when passing operands. The wrapper must decide where its own options end and where the downstream command’s options begin.

For diagnostics, print the count and each argument separately. Joining everything with "$*" can make zero arguments, an empty argument, and arguments containing separators look misleadingly similar. Bash printf’s %q is useful for showing otherwise invisible boundaries, but logging and forwarding serve different purposes. Forward the saved list itself; do not execute a reconstructed log line.

Check it quickly

Run this complete Bash block. It verifies a four-element list containing an empty value, a spaced pathname, a literal star, and an option-like value. It then checks function scope, the difference between the two quoted expansions with no arguments, and an attempted shift beyond the list length. No files or external services are needed.

bash --noprofile --norc <<'BASH'
set -e
IFS=$' \t\n'
set -- '' 'report final.md' '*.log' '--help'
saved=("$@")
verify() {
 [[ $# -eq 4 && $1 == '' && $2 == 'report final.md' ]]
 [[ $3 == '*.log' && $4 == '--help' ]]
 printf 'arg <%q>\n' "$@"
}
verify "${saved[@]}"
consume() {
 [[ $# -eq 2 ]]
 shift
 [[ $# -eq 1 && $1 == child-two ]]
 set -- replaced
 [[ $1 == replaced ]]
}
consume child-one child-two
[[ $# -eq 4 && $2 == 'report final.md' ]]
joined=$(IFS=,; printf '%s' "$*")
[[ $joined == ',report final.md,*.log,--help' ]]
count() { printf '%s' "$#"; }
set --
[[ $(count "$@") == 0 ]]
[[ $(count "$*") == 1 ]]
set -- sole
if shift 2; then
 printf 'unexpected shift success\n' >&2
 exit 1
fi
[[ $# -eq 1 && $1 == sole ]]
printf 'PASS: forwarding, function scope, empty list, shift limit\n'
BASH

Expect four escaped argument lines and the final PASS message. The first argument is explicitly empty, and the star remains literal. Returning from consume must leave the outer four-element list unchanged. A failed oversized shift must preserve the single remaining argument. These assertions test argument transport; a production wrapper still needs tests for its particular option grammar, required values, and downstream invocation.

Sources

GNU Bash: Special Parameters, positional-list expansions, joining, and counts, checked 2026-09-06.
GNU Bash: Arrays, saving and forwarding separate elements, checked 2026-09-06.
GNU Bash: Word Splitting, unquoted expansions and empty arguments, checked 2026-09-06.

Exit status is a compact report of what went wrong

Sat, 27 Mar 2027 00:00:00 +0000

An exit status is a small value that a shell uses to decide what runs next. Zero means success for shell control flow; a nonzero status takes the failure branch. That does not give every number a universal application meaning. A search with no matches, invalid input, and an unavailable server may deserve different handling even though all can produce nonzero results. Read the command’s contract before deciding what to retry or ignore.

Keep the status attached to its command

Bash exposes the most recent foreground command’s status through $?. Capture it before logging, testing another condition, or running cleanup. Those operations have statuses of their own and can replace the evidence you wanted. A function normally returns the status of its last executed command, so a successful final log message can accidentally turn an earlier failure into a successful function result.

Use if command; then ... else ... fi when the command’s success determines the next action. In the else branch, save $? immediately if the exact failure code matters. An explicit return or exit can then propagate that saved result after diagnostics. Avoid using if ! command and expecting $? inside the success branch to contain the original failure: the negation has already turned it into success.

Bash uses status 127 when command lookup fails and 126 when it finds a command that cannot be executed. It represents fatal signal termination as 128 plus the signal number. These conventions help interpret shell reports, but an application can explicitly exit with the same number. A numerical status alone is therefore not proof of which internal event happened. Keep stderr and the identity of the failed operation alongside it.

When it breaks

A pipeline defaults to its last stage’s status. An upstream generator can fail while a downstream reader successfully consumes an empty or partial stream. With pipefail enabled, Bash selects the rightmost nonzero stage status, or zero if every stage succeeds. PIPESTATUS exposes each stage separately, but subsequent commands replace that array too. Capture the complete observation before running another command.

Errexit, enabled by set -e, has exceptions determined by syntax and calling context. Failures used as if conditions, certain commands in AND or OR lists, and other documented contexts do not automatically exit. A function invoked as a condition can continue after a failed command in its body. An ERR trap follows similar exclusions and is not a report of every possible failure. Neither mechanism proves a script is safe.

Adding || true broadly discards useful distinctions. It may be appropriate when every failure from that exact operation is acceptable, but it can hide an unexpected permission error or an unavailable executable. Handle documented expected results specifically, and propagate unexpected ones. Likewise, first && second || recover runs recover when second fails too; it is not equivalent to an if statement that only tests first.

Background launch has another boundary: successfully starting a job does not mean the job completed successfully. Save its identifier from $! and inspect wait’s result for that job. If a script starts several jobs, retain each identifier and wait for each required result. Otherwise a final successful foreground command can mask work that failed after being launched.

Check it quickly

The following complete Bash experiment uses intentional failures and checks their exact propagation. It demonstrates immediate capture, negation, a function called in a conditional context, and a background job that fails after launch. It does not contact external services or require any files.

bash --noprofile --norc <<'BASH'
set -e
fail_seven() { return 7; }
if fail_seven; then
 exit 1
else
 saved=$?
fi
printf 'saved status %s\n' "$saved"
[[ $saved -eq 7 ]]
[[ $? -eq 0 ]]
if ! fail_seven; then
 negated=$?
fi
[[ $negated -eq 0 ]]
continued=no
conditional_function() {
 false
 continued=yes
}
if conditional_function; then
 [[ $continued == yes ]]
else
 exit 1
fi
(exit 6) &
job_pid=$!
if wait "$job_pid"; then
 exit 1
else
 job_status=$?
fi
[[ $job_status -eq 6 ]]
printf 'PASS: saved failure, negation, conditional context, wait\n'
BASH

Expect a saved status of seven and the final PASS message. The negated status is zero, and the conditional function reaches its assignment despite errexit being set. Wait must report the child’s six. These assertions expose control-flow boundaries; they do not assign meanings to an arbitrary tool’s codes. When adopting the pattern, test both expected negative results and unexpected operational failures, and verify that the wrapper exits with the result its caller needs.

Sources

GNU Bash: Exit Status, shell status conventions, checked 2026-09-06.
GNU Bash: The Set Builtin, errexit exclusions, checked 2026-09-06.
GNU Bash: Pipelines, aggregate pipeline results, checked 2026-09-06.

A shell function reads its arguments like a script

Tue, 16 Mar 2027 00:00:00 +0000

A shell function groups commands under a name and receives its own positional arguments. In an ordinary call, its body runs in the current shell rather than automatically starting a separate process. That makes functions useful for reusable operations, but it also means assignments, directory changes, and other shell state can affect the caller. A function needs an explicit contract for inputs, output, status, and any intentional side effects.

Arguments belong to each invocation

Calling demo_func first second makes those two values available as $1 and $2 inside that invocation, with $# equal to two. Another function call temporarily installs its own list. When it returns, the caller’s list is restored. Using shift within the callee therefore does not consume the caller’s positional arguments. In Bash, $0 does not change to the function name.

Forward the list with "$@" so empty arguments, spaces, and wildcard characters retain their boundaries. Validate the argument count before accessing required positions, and distinguish an omitted argument from a deliberately empty value. A function has no parameter declaration that automatically enforces those rules.

Local variables have dynamic scope

Bash’s local builtin creates a variable that shadows a name in an outer scope. When the function returns, that previous binding becomes visible again. Declare temporary values and loop counters locally when modifying the caller’s variable is not part of the interface. Portable shell code must not assume every interpreter implements Bash’s local-variable facilities.

However, Bash uses dynamic scope: a function called from another function can see the caller’s local variables. If it assigns to such a name without declaring its own local, it can modify the caller’s local binding. The outer global remains protected, but the calling function’s value changes. Local variables are not lexically private objects inaccessible to all other functions.

Local declarations also do not automatically restore the working directory, shell options, traps, or files modified by the body. Those effects need their own contract. Running a function inside ordinary command substitution instead gives it a subshell environment: its variable and directory changes do not propagate back, although file writes still can. Capturing output is not a general sandbox.

Status and data use different channels

A function’s status is the last executed command’s status unless an explicit return changes it. Use standard output for the documented payload and standard error for diagnostics. return 7 reports a status to the caller; it does not return the text seven as data. exit terminates the executing shell rather than merely returning from the function.

Separate a local declaration from a command-substitution assignment when the producer’s status matters. In local result=$(producer), the observed status belongs to the declaration builtin and can hide the producer’s failure. A subsequent assignment without the declaration has the substitution’s status. Capture that result before logging or cleanup changes it.

When it breaks

An unlocalized counter can corrupt a calling loop, including one using a local variable of its own. Tests should call helpers from another function as well as from top-level code. A global-only test misses the dynamic-scope interaction. An unexpected progress message on standard output similarly corrupts callers that capture a single promised value.

Do not rely on set -e to make a function fail predictably at every failed command. Its effect depends on calling context; a function used as an if condition can continue after failures inside its body. Explicitly check operations whose failure must stop subsequent work, and propagate the required status after any diagnostics.

Check it quickly

Run this complete block in Bash. It changes only variables and positional arguments inside a fresh shell. The worker intentionally modifies its caller’s local variable, while the second function demonstrates argument preservation and a nonzero return. The final pair contrasts combined declaration with separate assignment.

BASH_ENV= bash --noprofile --norc <<'BASH'
demo_value=global
demo_worker() { demo_value=changed; }
demo_scope() {
 local demo_value=inner
 printf 'local-before=%s\n' "$demo_value"
 demo_worker
 printf 'local-after=%s\n' "$demo_value"
}
demo_scope
printf 'global-after=%s\n' "$demo_value"
demo_args() {
 local demo_arg
 printf 'function-count=%s\n' "$#"
 for demo_arg in "$@"; do printf 'argument=<%s>\n' "$demo_arg"; done
 shift
 printf 'after-shift=%s\n' "$#"
 return 7
}
set -- outer-one outer-two
if demo_args '' 'two words'; then
 exit 99
else
 demo_status=$?
fi
printf 'function-status=%s outer-count=%s outer-first=%s\n' "$demo_status" "$#" "$1"
demo_masked() { local demo_result=$(return 9); }
demo_checked() {
 local demo_result
 demo_result=$(return 9)
}
demo_masked
printf 'combined-declaration=%s\n' "$?"
if demo_checked; then exit 99; else printf 'separate-assignment=%s\n' "$?"; fi
BASH

Expect the local value to change from inner to changed, but the global value to remain global. Both supplied arguments print separately, including the empty one. The function returns seven after shifting its list; the outer shell still has two arguments beginning with outer-one. Finally, the combined declaration reports zero while the separate assignment reports nine. These results test the actual calling boundaries rather than assuming every variable called local is isolated.

Sources

Bash shell functions, function argument lists and dynamic variable scope, checked 2026-09-07.
Bash-specific builtins, local declaration behavior and return status, checked 2026-09-07.
Bash set builtin, errexit behavior when a function is used as a condition, checked 2026-09-07.

Command substitution puts one command's output into another line

Wed, 03 Mar 2027 00:00:00 +0000

Command substitution captures a command’s standard output and inserts the resulting text into a surrounding expression. The familiar $(command) form is useful for a timestamp, a computed label, or another small textual value. It is not a transparent channel for arbitrary bytes or a reliable way to transport a list of filenames. Its newline handling, execution environment, and exit status are part of the interface you need to understand.

Capture text, then decide how to use it

For the standard substitution form discussed here, Bash executes the enclosed commands in a subshell environment. It captures standard output and removes all trailing newline characters. Newlines inside the output remain. Double quotes prevent later word splitting and filename expansion, but they do not undo the removal of trailing newlines. If the exact final bytes matter, use a file or a stream instead of a shell variable.

A variable assignment such as result=$(producer) stores the resulting text without splitting it into arguments. When using the value later, write "$result" to preserve its boundary. Similarly, consumer "$(producer)" supplies a single argument, even when the captured result is empty. Leaving the substitution unquoted can create several arguments or no arguments, and stars in the output may match filenames in the working directory.

Standard error is separate from standard output unless you explicitly redirect it. A diagnostic can remain visible on the terminal while the captured value contains only the result. Redirecting both streams together may contaminate a machine-readable value with warning text. Design the producer’s output contract before deciding whether those streams belong together; suppressing every diagnostic can hide the reason a value is missing.

When it breaks

The subshell has its own variable changes and working directory. Assigning a variable or running cd inside the substitution does not update the caller’s corresponding state. Filesystem and network side effects still happen, however: creating a file inside the substitution creates a real file. Process isolation does not make an operation reversible or remove its external effects.

Successful capture also says nothing about whether the producer succeeded. An assignment-only command gets the status of its last command substitution, so if result=$(producer); then can check the result. In contrast, the status of printf '%s' "$(producer)" normally describes printf. A producer can emit partial output and then fail; retain its status immediately and decide whether that output is usable. A later logging command overwrites the value represented by $?.

Avoid relying on an implicit failure somewhere inside a multi-command substitution. Its final command can return success even after an earlier command failed. Explicitly test important operations in the producer and return the intended status. Likewise, in a function, separate a local declaration from the capturing assignment when you need to inspect the producer’s status; a declaration builtin can mask that status.

Substitution also collects output before the surrounding command runs, so it is unsuitable for unbounded output or interactive streaming. Do not use an unquoted substitution over find output to construct an arbitrary pathname list: whitespace and wildcard characters lose their original meaning. Pass filenames through an interface that retains boundaries, such as find’s exec facility, or use a deliberately specified record protocol.

Check it quickly

Run this complete block with Bash. It uses only shell builtins and asserts the output and status independently. No files or services need to be prepared. The producer with status seven is an intentional failure, and the test must still reach the final PASS line.

bash --noprofile --norc <<'BASH'
set -e
outer=parent
captured=$(outer=child; printf 'first\nsecond\n\n')
[[ $outer == parent ]]
[[ $captured == $'first\nsecond' ]]
printf 'captured <%q>\n' "$captured"
if partial=$(printf 'incomplete'; exit 7); then
 printf 'unexpected producer success\n' >&2
 exit 1
else
 status=$?
fi
[[ $status -eq 7 && $partial == incomplete ]]
printf 'producer status %s; partial <%s>\n' "$status" "$partial"
printf '%s' "$(exit 9)"
[[ $? -eq 0 ]]
IFS=$' \t\n'
set -- "$(printf 'two words\n')"
[[ $# -eq 1 && $1 == 'two words' ]]
set -- "$(printf '\n\n')"
[[ $# -eq 1 && $1 == '' ]]
printf 'PASS: capture, subshell scope, failure status, empty result\n'
BASH

The escaped captured value should contain one internal newline and no trailing newline. The next line reports status seven alongside the partial text. The deliberately successful outer printf demonstrates why checking only the consumer’s status misses producer failure. These checks establish the behavior of the small synchronous producers shown here. A real producer still needs its own timeout, output-format validation, and explicit error contract where those requirements apply.

Sources

GNU Bash: Command Substitution, standard substitution scope and newline handling, checked 2026-09-06.
GNU Bash: Word Splitting, treatment of unquoted captured output, checked 2026-09-06.
GNU Bash: Special Parameters, the status exposed by the question-mark parameter, checked 2026-09-06.

A here-string pipes text into a command's stdin

Mon, 15 Feb 2027 00:00:00 +0000

A Bash here-string supplies the expanded value of one word to a command’s standard input, with a newline appended. It is convenient when a small textual value already exists in a variable and the receiving tool reads stdin. The syntax removes the need for a separate printing command, but it does not promise byte-for-byte identity with the variable or a particular implementation using memory, a pipe, or a file.

Expansion happens before the input is read

The word after the triple-less-than operator can contain parameter expansion, arithmetic expansion, or command substitution. It is therefore not necessarily a literal constant. Single quotes preserve literal source text, while double quotes permit the usual variable and command expansions. Text obtained by expanding a variable is not recursively executed as shell code merely because it contains a dollar sign and parentheses.

In current Bash, a here-string’s word does not undergo word splitting or filename expansion. It is delivered as a single string. Quoting a variable in this position still makes the intended boundary easy to read, but do not confuse this redirection context with passing an unquoted variable as a normal command argument. The latter can split the value and expand wildcard characters into filenames.

The appended newline is unconditional. A value without a final newline gains one; a value already ending in a newline gains another. An empty variable consequently produces a one-byte input containing a newline, rather than immediate end-of-file. This makes here-strings natural for many line-oriented tools and unsuitable when the receiving protocol requires an exact length or a specific final byte.

When it breaks

Read applies its own interpretation after the shell constructs the input. By default, its field splitting can remove surrounding IFS whitespace, and backslashes can act as escapes. For one line whose spaces and backslashes must be retained, use IFS= read -r name. This protects the line’s content, but a single read still stops at the first newline. It does not capture an arbitrary multiline value into that variable.

A redirected builtin or loop can run in the current shell, so its assignments remain visible. That is useful compared with a loop placed in a pipeline, where Bash normally runs the stage in a subshell. The input redirection itself does not create a subshell around the command. An explicit subshell or command substitution elsewhere in the expression still has its usual scope and effects.

The absence of an explicit filename in the script does not establish how Bash stores the redirection internally. Avoid code that depends on stdin being seekable, on a fixed buffering capacity, or on there being no temporary backing storage. For large existing files, direct file redirection avoids first collecting the whole input in a shell variable. For exact textual bytes, a carefully formatted printf or a file can avoid the added newline.

Here-strings are also a shell-language feature, not portable syntax for every interpreter called sh. A script using them should select an interpreter that supports them, and tests should invoke that interpreter explicitly. Conversely, changing an echo pipeline to a here-string can alter both newline behavior and variable scope. Compare the consumer’s observed bytes and state changes rather than treating the forms as interchangeable typography.

Check it quickly

This complete fixture needs Bash and Python 3. Python displays stdin as hexadecimal so appended newline bytes remain visible; capturing that hexadecimal output does not lose the input bytes being inspected. The remaining checks use read and a redirected loop to test whitespace preservation, literal text, and multiline consumption. No fixture files are required.

bash --noprofile --norc <<'BASH'
set -e
hex_input() {
 python3 -c 'import sys; print(sys.stdin.buffer.read().hex())'
}
[[ $(hex_input <<< X) == 580a ]]
[[ $(hex_input <<< '') == 0a ]]
[[ $(hex_input <<< $'X\n') == 580a0a ]]
[[ $(printf '%s' X | hex_input) == 58 ]]
value=' a\b *.txt '
IFS= read -r received <<< "$value"
[[ $received == "$value" ]]
literal='$(printf injected)'
IFS= read -r received <<< "$literal"
[[ $received == '$(printf injected)' ]]
value=$'one\ntwo'
IFS= read -r first <<< "$value"
[[ $first == one ]]
lines=0
while IFS= read -r line; do
 lines=$((lines + 1))
done <<< "$value"
[[ $lines -eq 2 ]]
printf 'PASS: newline bytes, preserved text, single read, loop scope\n'
BASH

Expect only the PASS line. The hexadecimal assertions distinguish one newline from two and compare a here-string with printf that adds none. The literal command-looking text must remain unchanged, and the loop count must survive in the outer shell. These results test the documented input behavior, not the internal storage mechanism. Before using the pattern with another reader, check how that reader handles empty lines, multiple records, and trailing whitespace of its own.

Sources

GNU Bash: Redirections, here-string expansion and appended newline, checked 2026-09-06.
GNU Bash: Bash Builtins, read delimiters and raw-input mode, checked 2026-09-06.
GNU Bash: Command Substitution, captured output and trailing-newline removal, checked 2026-09-06.

case runs one branch that matches a pattern

Sat, 30 Jan 2027 00:00:00 +0000

A case statement routes one value through an ordered list of shell patterns. It is useful for a command dispatcher, a small set of accepted answers, or filename-suffix classification. Each branch states the values it handles, and several patterns can share one body. The ordering and the default branch are part of the interface: they decide what happens when an input overlaps several categories or belongs to none.

Patterns match the whole value

Case uses shell patterns, not regular expressions. A star matches any string, a question mark matches one character, and brackets specify a character set or range. Thus [0-9]* means a digit followed by anything; it does not mean an entire nonempty string of digits. To validate a decimal identifier without arithmetic interpretation, first reject an empty string and any string containing a non-digit.

The alternatives in start|up|run) share an action. A broad suffix pattern such as *.log) can classify a string without opening a file or searching the directory. Unlike pathname expansion, this matching does not establish that the named resource exists. A slash or leading dot also does not have the special exclusion role it has during ordinary filename expansion. Classification and filesystem validation remain separate operations.

The word being tested undergoes the documented expansions, but Bash does not word-split or glob it as ordinary command arguments. An empty unquoted variable in that position does not delete the syntactic word and cause a case syntax error. Quoting the tested value is still clear style. With nounset enabled, separately handle a missing positional parameter or validate the argument count; quotation alone does not make an unset parameter available.

When it breaks

With the usual double-semicolon terminator, the first matching branch runs and case finishes. Put exact values before broader families and the catch-all star last. Otherwise a generic option branch can swallow a later exact status command. Syntax checking cannot establish that your ordering expresses the intended precedence; exercise an input matching both patterns and assert which action runs.

If no branch matches, case returns zero without running an action. A missing default is therefore not automatically an error. A dispatcher that rejects unknown commands must explicitly report and return failure in its default branch. Conversely, an optional classification may deliberately allow no match. Decide that policy from the caller’s contract, rather than assuming case supplies input validation on its own.

Quoting a pattern changes its meaning. A quoted "*.log" matches the literal characters, whereas the unquoted pattern matches a suffix family. The same distinction matters when a variable supplies a pattern: decide whether it is a trusted matching expression or literal text. Do not accidentally grant wildcard behavior to an identifier that should be compared exactly.

Bash options and versions introduce further boundaries. Nocasematch changes case sensitivity, while extended patterns need extglob enabled before the relevant code is parsed. Newer Bash also provides branch terminators that continue execution or resume matching; do not assume they behave like double semicolons or work in older shells. The experiment below deliberately uses ordinary patterns and double semicolons compatible with Bash 3.2.

Check it quickly

Run this complete Bash block. Its dispatcher includes exact commands, grouped aliases, a wildcard family, an explicit empty-input error, and an unknown-input error. A second function checks decimal text without accepting a digit followed by letters. The assertions test results and error codes rather than merely looking for a successful script exit.

bash --noprofile --norc <<'BASH'
set -e
export LC_ALL=C
shopt -u nocasematch
route() {
 case "${1-}" in
 status|--status) printf '%s' status ;;
 start|up|run) printf '%s' start ;;
 '') return 2 ;;
 --*) return 3 ;;
 *.log) printf '%s' log ;;
 *) return 4 ;;
 esac
}
[[ $(route --status) == status ]]
[[ $(route up) == start ]]
[[ $(route 'report final.log') == log ]]
expect_error() {
 local expected=$1
 shift
 if route "$@"; then
 return 1
 else
 local actual=$?
 [[ $actual -eq $expected ]]
 fi
}
expect_error 2 ''
expect_error 2
expect_error 3 --unknown
expect_error 4 STATUS
digits() {
 case "${1-}" in
 ''|*[!0-9]*) return 1 ;;
 *) return 0 ;;
 esac
}
digits 007
if digits 7abc; then exit 1; fi
if digits ''; then exit 1; fi
empty=''
matched=no
case $empty in '') matched=yes ;; esac
[[ $matched == yes ]]
case unmatched in known) exit 1 ;; esac
[[ $? -eq 0 ]]
printf 'PASS: precedence, aliases, empty input, validation, no match\n'
BASH

Expect the PASS line with no earlier output. The exact status option must bypass the generic option error, and uppercase STATUS must be rejected because case-insensitive matching is disabled. The final checks demonstrate that an empty expanded word is valid and that no match returns success. These tests cover routing decisions only; replace the harmless actions with real operations only after testing their arguments, side effects, and failure propagation separately.

Sources

GNU Bash: Conditional Constructs, case ordering, expansion, and return status, checked 2026-09-06.
GNU Bash: Pattern Matching, wildcard and extended-pattern semantics, checked 2026-09-06.
GNU Bash: Word Splitting, contexts that split expanded values, checked 2026-09-06.

Shell traps turn a signal into a cleanup step

Tue, 12 Jan 2027 00:00:00 +0000

A trap lets a shell arrange an action for a signal or a shell event. It is useful for removing temporary files and coordinating shutdown, but it does not make interruption atomic or guarantee cleanup under every termination. In Bash, trap is a builtin, and EXIT is a shell event rather than an operating system signal. A reliable design names the exits it handles and preserves evidence of why execution stopped.

Separate a signal handler from the exit handler

trap 'cleanup' INT TERM replaces the default action for those signals. If the handler simply returns, the shell can continue executing; installing a handler does not inherently mean shutdown. One clear Bash pattern has the signal handlers explicitly exit, with a shared EXIT handler doing cleanup. Normal completion and explicit exit also reach that handler.

Returning from a function or a sourced file is not the same as terminating the shell. A top-level return in an ordinary executed script is not a general exit mechanism. Nor should a script assume that an unhandled fatal signal will always trigger EXIT across shells. Handle the intended termination signals explicitly and test with the actual interpreter used by the service.

trap - INT restores the default action; trap '' INT ignores the signal. They are different policies. Noninteractive shells can also inherit ignored signals that they cannot reset or trap, so launcher behavior matters. Inspect registered actions with trap -p when diagnosis requires confirming what was installed.

Preserve the reason for leaving

At entry to the exit handler, save $? before another command overwrites it. Cleanup that ends with an unconditional exit 1 converts successful work into failure and hides distinct error codes. Exiting with the saved value preserves the initiating outcome. Cleanup failures still need visible diagnostics and a deliberate policy, especially if the main work succeeded.

The example chooses 130 for handled INT and 143 for handled TERM, following Bash’s familiar signal-status convention. Those are explicit normal exits, not proof that the process was actually killed by a signal. A supervisor using the process API can distinguish the two. Here, disabling the exit trap and ignoring INT and TERM during the short cleanup prevents those handlers from reentering it.

When it breaks

SIGKILL cannot be caught, and SIGSTOP cannot be caught or used as a cleanup opportunity. Power loss, crashes, and forced termination can leave resources behind. A trap is therefore not a replacement for crash-safe writes, transactional updates, or a separately defined recovery procedure. Restrict removal to paths the script owns; a partially initialized variable must never become a broad deletion target.

Timing also matters. Bash can defer a trapped signal while waiting for a synchronous foreground command to finish. When it is waiting through the wait builtin for an asynchronous command, a trapped signal instead interrupts that wait before the handler runs. Registering a trap does not establish an immediate shutdown deadline for arbitrary blocking work.

Terminal Ctrl-C sends INT to the foreground process group, whereas signaling one PID targets that process. A child may therefore see the signal in one test but not the other. Scripts managing workers must define signal forwarding, waiting, and ownership of those workers. Killing unrelated processes or treating the shell’s exit as proof that every descendant stopped is not cleanup.

Check it quickly

Run this with Python 3, Bash, and standard Unix utilities. Each case starts a separate Bash process that creates one file in a private temporary directory. Signals target only that new shell itself. Python owns the outer directory and removes the deliberately retained KILL artifact afterward.

import os
import signal
import subprocess
import tempfile
from pathlib import Path

script = r'''
demo_file=$1
cleanup() {
 demo_status=$?
 trap - EXIT
 trap '' INT TERM
 rm -f -- "$demo_file"
 printf 'cleanup=%s\n' "$demo_status"
 exit "$demo_status"
}
trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
: > "$demo_file" || exit 1
case "$2" in
 normal) exit 7 ;;
 *) kill "-$2" "$$" ;;
esac
exit 99
'''
with tempfile.TemporaryDirectory(prefix="bash-trap-demo-") as directory:
 for mode, expected in [("normal", 7), ("TERM", 143),
 ("INT", 130), ("KILL", -signal.SIGKILL)]:
 target = Path(directory) / mode
 result = subprocess.run(
 ["bash", "--noprofile", "--norc", "-c", script,
 "trap-demo", str(target), mode],
 env=dict(os.environ, BASH_ENV=""),
 text=True, capture_output=True, timeout=5,
 )
 cleaned = result.stdout == f"cleanup={expected}\n"
 remains = target.exists()
 assert result.returncode == expected, result
 assert (cleaned, remains) == (mode != "KILL", mode == "KILL"), result
 assert not result.stderr, result
 print(f"{mode}: rc={result.returncode} cleaned={cleaned} remains={remains}")

Expect return codes 7, 143, and 130 with cleanup observed and no remaining file. KILL yields Python’s negative signal return code, normally -9, with no cleanup output and a remaining file. An invoking shell would conventionally report 137 instead. The contrast verifies preserved status and the uncatchable boundary; it does not test worker forwarding, terminal process groups, or delayed traps around long-running commands.

Sources

Bash signals, signal handling while waiting and foreground process groups, checked 2026-09-07.
POSIX trap, exit events, inherited signal dispositions, and trap actions, checked 2026-09-07.

Shell · XB Field Notes

Bash history is your searchable command log

Session memory differs from the file

Appending does not refresh other terminals

Search, inspect, then execute

When it breaks

Check it quickly

Sources

Shell word splitting turns unquoted variables into several arguments

Splitting depends on the context

When it breaks

Check it quickly

Sources

Shell positional arguments are a numbered list

Preserve the list before interpreting it

Let getopts report syntax, then validate meaning

When it breaks

Check it quickly

Sources

Shell parameter expansion rewrites values

Defaults distinguish missing from empty

Patterns transform strings, not files

When it breaks

Check it quickly

Sources

Umask filters new permissions, with a default ACL exception

When it breaks

Check it quickly

Apply creation policy at the right layer

Sources

Shell aliases shrink repeated typing

Replacement happens when input is read

Scope and timing are different questions

When it breaks

Check it quickly

Further reading

Sources

Redirection reorders the streams

Opening a file is already a side effect

Duplication captures the current destination

When it breaks

Check it quickly

Further reading

Sources

Shell pipes stream between processes

A byte stream with finite capacity

When it breaks

Check it quickly

Sources

Job control moves terminal foreground ownership between groups

When it breaks

Check it quickly

Choose the intended lifetime and input source

Sources

Environment variables are a per-process thing

Export selects values for another program

A subshell is not a freshly executed shell

Per-command settings have a defined lifetime

When it breaks

Check it quickly

Sources

Bash globbing expands before the command runs

Match first, then preserve the arguments

When it breaks

Check it quickly

Sources

A bare command the shell cannot find

Know which lookup layer answered

A slash selects a path directly

When it breaks

Check it quickly

Sources

$@ and friends give a function its whole argument list

A list is different from joined text

When it breaks

Check it quickly

Sources

Exit status is a compact report of what went wrong

Keep the status attached to its command

When it breaks