bitranox/bx-bash-reference

Bash 5.3 Reference

Overview

Complete reference for GNU Bash 5.3 (May 2025). Covers all shell syntax, builtins, variables, expansions, redirections, and features. Use this skill whenever writing or reviewing bash scripts to ensure correctness.

This file is a scannable hub. Each section below summarizes key constructs with compact tables. Use the Read tool to load referenced files identified as relevant for full syntax, edge cases, and examples:

• Syntax & commands (quoting, compound commands, pipelines): shell-syntax-and-commands.md
• Functions, parameters & expansions (all expansion types, pattern matching): functions-parameters-expansions.md
• Redirections & execution (I/O, here docs, FDs, command search, signals): redirections-and-execution.md
• Builtins (set, shopt, declare, read, printf, trap, etc.): shell-builtins.md
• Variables (BASH_REMATCH, PIPESTATUS, EPOCHSECONDS, etc.): shell-variables.md
• Bash features (startup files, arrays, arithmetic, POSIX mode, conditionals): bash-features.md
• Job control, readline & history (bg/fg, completion, history expansion): job-control-readline-history.md

When to Use

• Need exact syntax for any Bash construct (loops, conditionals, expansions, redirections)
• Writing, reviewing, or debugging Bash scripts
• Unsure about quoting rules, expansion order, or operator behavior
• Need to look up a specific builtin, variable, shopt option, or test operator
• Verifying Bash 5.3-specific features (${ command; }, GLOBSORT, BASH_MONOSECONDS)

When NOT to Use

• Writing POSIX-portable sh scripts (this covers Bash-specific features beyond POSIX)
• Zsh, Fish, or other shell syntax
• Structuring multi-file Bash projects (use bash_clean_architecture instead)

Reference Files

| File | Contents | |--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | shell-syntax-and-commands.md | Quoting, comments, reserved words, pipelines, lists, compound commands (if/for/while/case/select/[[/(( ), grouping, coprocesses | | functions-parameters-expansions.md | Shell functions, positional/special parameters, ALL expansion types (brace, tilde, parameter, command substitution, arithmetic, process substitution, word splitting, globbing, pattern matching) | | redirections-and-execution.md | All redirection types, here docs/strings, file descriptors, command search/execution, execution environment, exit status, signals, shell scripts | | shell-builtins.md | All Bourne shell builtins, all Bash builtins, set options, shopt options, special builtins | | shell-variables.md | All Bourne shell variables, all Bash variables (BASH_, COMP_, HIST*, READLINE_*, etc.) | | bash-features.md | Invocation options, startup files, interactive shell behavior, conditional expressions, arithmetic, aliases, arrays, directory stack, prompt control, restricted shell, POSIX mode, compatibility mode | | job-control-readline-history.md | Job control (bg/fg/jobs/disown), readline configuration, all bindable commands, vi mode, programmable completion (complete/compgen/compopt), history expansion |

Which File Do I Need?

| I need to... | Read | |--------------------------------------------------------------------------------------|--------------------------------------| | Write a function, use parameters/expansions, do string manipulation | functions-parameters-expansions.md | | Use if/for/while/case/select/[[ ]]/(( )), or understand quoting | shell-syntax-and-commands.md | | Redirect I/O, use here docs/strings, understand fd management | redirections-and-execution.md | | Look up a builtin (set, shopt, declare, read, printf, trap, etc.) | shell-builtins.md | | Check a shell variable (BASH_REMATCH, PIPESTATUS, EPOCHSECONDS, etc.) | shell-variables.md | | Understand startup files, arrays, arithmetic, POSIX mode, or conditional expressions | bash-features.md | | Work with job control, readline, completion, or history expansion | job-control-readline-history.md |

Quick Reference: Most-Used Constructs

Quoting

Full details: shell-syntax-and-commands.md (section 1)

| Syntax | Behavior | |-----------|------------------------------------------------------------------| | \x | Escape single character | | 'text' | Literal string, no expansion | | "text" | Allows $, `, \, ! expansion | | $'text' | ANSI-C escapes: \n, \t, \e, \xHH, \uHHHH, \UHHHHHHHH | | $"text" | Locale-specific translation |

Parameter Expansion

Full details: functions-parameters-expansions.md (section 3.4)

| Syntax | Result | |------------------------|----------------------------------| | ${var:-default} | Use default if var unset/null | | ${var:=default} | Assign default if var unset/null | | ${var:+alternate} | Use alternate if var IS set | | ${var:?error} | Error if var unset/null | | ${#var} | String length | | ${var:offset:length} | Substring | | ${var#pattern} | Remove shortest prefix match | | ${var##pattern} | Remove longest prefix match | | ${var%pattern} | Remove shortest suffix match | | ${var%%pattern} | Remove longest suffix match | | ${var/pat/str} | Replace first match | | ${var//pat/str} | Replace all matches | | ${var/#pat/str} | Replace if matches beginning | | ${var/%pat/str} | Replace if matches end | | ${var^pattern} | Uppercase first char | | ${var^^pattern} | Uppercase all chars | | ${var,pattern} | Lowercase first char | | ${var,,pattern} | Lowercase all chars | | ${!prefix*} | Names matching prefix | | ${!name[@]} | Array indices/keys | | ${!var} | Indirect expansion | | ${var@Q} | Quote for reuse | | ${var@E} | Expand escape sequences | | ${var@P} | Expand as prompt string | | ${var@A} | Assignment statement form | | ${var@a} | Attribute flags | | ${var@U} | Uppercase all | | ${var@u} | Uppercase first | | ${var@L} | Lowercase all | | ${var@K} | Key-value pairs (assoc arrays) |

Special Parameters

Full details: functions-parameters-expansions.md (section 2)

| Param | Meaning | |---------------------|-------------------------------------------------| | $0 | Script/shell name | | $1..$9, ${10} | Positional parameters | | $# | Number of positional parameters | | $* | All positional params as single word (with IFS) | | $@ | All positional params as separate words | | "$*" | "$1c$2c..." where c = first char of IFS | | "$@" | "$1" "$2" ... (preserves word boundaries) | | $? | Exit status of last command | | $$ | PID of the shell | | $! | PID of last background command | | $- | Current option flags | | $_ | Last argument of previous command |

Compound Commands

Full details: shell-syntax-and-commands.md (section 3)

# If
if cmd; then ...; elif cmd; then ...; else ...; fi

# For
for var in words; do ...; done
for (( init; test; step )); do ...; done

# While / Until
while cmd; do ...; done
until cmd; do ...; done

# Case
case word in
    pattern1|pattern2) commands ;;   # break
    pattern3) commands ;&            # fall-through
    pattern4) commands ;;&           # test next
esac

# Select (menu)
select var in words; do ...; done

# Test
[[ expression ]]    # Preferred (no word splitting/globbing)
(( expression ))    # Arithmetic evaluation

# Grouping
{ commands; }       # Current shell (note: space after {, ; before })
( commands )        # Subshell

Test Operators ([[ ]] and test/[ ])

Full details: bash-features.md (section 4)

| Operator | Test | |-----------------------|----------------------------------| | -e file | Exists | | -f file | Regular file | | -d file | Directory | | -L file / -h file | Symlink | | -s file | Non-zero size | | -r file | Readable | | -w file | Writable | | -x file | Executable | | -p file | Named pipe | | -S file | Socket | | -b file | Block device | | -c file | Character device | | -t fd | FD is terminal | | -O file | Owned by effective UID | | -G file | Owned by effective GID | | -N file | Modified since last read | | f1 -nt f2 | f1 newer than f2 | | f1 -ot f2 | f1 older than f2 | | f1 -ef f2 | Same inode | | -v var | Variable is set | | -R var | Variable is nameref | | -z string | Zero length | | -n string | Non-zero length | | s1 == s2 | Equal (pattern match in [[ ]]) | | s1 != s2 | Not equal | | s1 < s2 | Less than (lexicographic) | | s1 > s2 | Greater than (lexicographic) | | s1 =~ regex | Regex match ([[ ]] only) | | n1 -eq n2 | Numeric equal | | n1 -ne n2 | Numeric not equal | | n1 -lt n2 | Numeric less than | | n1 -le n2 | Numeric less/equal | | n1 -gt n2 | Numeric greater than | | n1 -ge n2 | Numeric greater/equal |

Redirections

Full details: redirections-and-execution.md (section 1)

| Syntax | Operation | |--------------------------------------|------------------------------------| | cmd < file | Stdin from file | | cmd > file | Stdout to file (truncate) | | cmd >> file | Stdout to file (append) | | cmd 2> file | Stderr to file | | cmd &> file or cmd > file 2>&1 | Stdout+stderr to file | | cmd &>> file or cmd >> file 2>&1 | Stdout+stderr append | | cmd >| file | Force overwrite (noclobber) | | cmd <<EOF | Here document | | cmd <<-EOF | Here document (strip leading tabs) | | cmd <<< "string" | Here string | | cmd <&fd | Duplicate input FD | | cmd >&fd | Duplicate output FD | | cmd fd<&- | Close input FD | | cmd fd>&- | Close output FD | | cmd n<>file | Open for read+write on FD n | | cmd {var}> file | Auto-assign FD to var |

Special filenames in redirections: /dev/fd/N, /dev/stdin, /dev/stdout, /dev/stderr, /dev/tcp/host/port, /dev/udp/host/port

Arrays

Full details: bash-features.md (section 6)

# Indexed arrays
declare -a arr=(one two three)
arr[0]="value"
arr+=(more items)

# Associative arrays (Bash 4.0+)
declare -A map=([key1]=val1 [key2]=val2)
map[key]="value"

# Access
${arr[0]}           # Single element
${arr[@]}           # All elements (separate words)
${arr[*]}           # All elements (single word with IFS)
${#arr[@]}          # Number of elements
${!arr[@]}          # All indices/keys
${arr[@]:off:len}   # Slice

# Unset
unset 'arr[2]'      # Remove element (quote to prevent glob)
unset arr            # Remove entire array

Expansion Order

1. Brace expansion
2. Tilde expansion
3. Parameter and variable expansion
4. Arithmetic expansion
5. Command substitution (left-to-right)
6. Process substitution
7. Word splitting
8. Filename expansion (globbing)
9. Quote removal

Steps 2-6 happen left-to-right simultaneously. Full details with word-count impacts: functions-parameters-expansions.md (section 3.5).

Common set Options

Full details: shell-builtins.md (section 2, set builtin)

| Option | Effect | |------------------------|------------------------------------------------| | set -e (errexit) | Exit on error (with exceptions) | | set -u (nounset) | Error on unset variables | | set -o pipefail | Pipeline fails if any command fails | | set -x (xtrace) | Print commands before execution | | set -f (noglob) | Disable filename expansion | | set -n (noexec) | Read commands without executing (syntax check) | | set -o posix | POSIX compliance mode | | set -E (errtrace) | ERR trap inherited by functions | | set -T (functrace) | DEBUG/RETURN traps inherited by functions |

Essential shopt Options

Full details: shell-builtins.md (section 3, shopt options)

| Option | Effect | |---------------------|-----------------------------------------------------------------| | extglob | Extended patterns: ?(pat) *(pat) +(pat) @(pat) !(pat) | | globstar | ** matches directories recursively | | nullglob | Unmatched globs expand to nothing | | failglob | Unmatched globs cause error | | nocaseglob | Case-insensitive globbing | | nocasematch | Case-insensitive case and [[ == ]] | | dotglob | Globs match dotfiles | | lastpipe | Last pipeline command runs in current shell | | inherit_errexit | Command substitutions inherit errexit | | assoc_expand_once | Expand associative array subscripts once |

Trap Signals

Full details: shell-builtins.md (trap builtin) and redirections-and-execution.md (section 5, Signals)

trap 'cleanup' EXIT          # On shell exit
trap 'handle_err' ERR        # On command error (with set -e)
trap 'on_debug' DEBUG        # Before every command
trap 'on_return' RETURN      # After function/sourced script returns
trap 'handle_int' INT        # Ctrl-C
trap 'handle_term' TERM      # kill signal
trap '' SIGNAL               # Ignore signal
trap - SIGNAL                # Reset to default

Arithmetic Operators (inside (( )) and $(( )))

Full details: bash-features.md (section 5)

All C-style operators: +, -, *, /, %, ** (exponent), <<, >>, &, |, ^, ~, !, &&, ||, <, >, <=, >=, ==, !=, =, +=, -=, *=, /=, %=, <<=, >>=, &=, |=, ^=, ++, --, expr?expr:expr (ternary), expr,expr (comma)

Bases: 0x (hex), 0 (octal), 0b (binary), base#number (arbitrary base 2-64)

Prompt Escape Sequences

Full details: bash-features.md (section 8, Controlling the Prompt)

| Escape | Meaning | |-----------|-------------------------------| | \u | Username | | \h | Hostname (short) | | \H | Hostname (full) | | \w | Working directory | | \W | Basename of working directory | | \d | Date (Day Mon Date) | | \t | Time (HH:MM:SS 24hr) | | \T | Time (HH:MM:SS 12hr) | | \@ | Time (AM/PM) | | \A | Time (HH:MM 24hr) | | \D{fmt} | strftime format | | \j | Number of jobs | | \! | History number | | \# | Command number | | \$ | # if root, $ otherwise | | \[ | Begin non-printing chars | | \] | End non-printing chars |

Definitions

| Term | Definition | |----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | blank | Space or tab | | word | Sequence of characters treated as a unit (no unquoted metacharacters) | | token | A word or an operator | | metacharacter | Unquoted: space, tab, newline, \|, &, ;, (, ), <, > | | control operator | \|\|, &&, &, ;, ;;, ;&, ;;&, \|, \|&, (, ), newline | | name/identifier | Letters, numbers, underscores; starts with letter or underscore | | exit status | 0-255; 0 = success, 1 = general error, 2 = usage error, 126 = not executable, 127 = not found, 128+N = killed by signal N | | special builtin | POSIX-designated builtins that have special properties (break, :, ., continue, eval, exec, exit, export, readonly, return, set, shift, trap, unset) |

Common Patterns

Safe Script Header

#!/usr/bin/env bash
set -euo pipefail

Temporary Files

tmpfile=$(mktemp) || exit 1
trap 'rm -f "$tmpfile"' EXIT

Read File Line by Line

while IFS= read -r line; do
    printf '%s\n' "$line"
done < "$file"

Default Values

name="${1:-default}"        # Use default if $1 unset/empty
name="${1:?'missing arg'}"  # Exit with error if $1 unset/empty

String Operations

# Lowercase / Uppercase
lower="${str,,}"
upper="${str^^}"
first_cap="${str^}"

# Trim prefix/suffix
filename="${path##*/}"      # basename
dir="${path%/*}"            # dirname
ext="${file##*.}"           # extension
noext="${file%.*}"          # remove extension

Array Iteration

for item in "${arr[@]}"; do echo "$item"; done       # values
for i in "${!arr[@]}"; do echo "$i: ${arr[$i]}"; done # index: value

Process Substitution

diff <(sort file1) <(sort file2)
while IFS= read -r line; do ...; done < <(cmd)  # avoid subshell

Associative Array Check

declare -A map
if [[ -v map["key"] ]]; then echo "exists"; fi

Common Mistakes

Unquoted variables (word splitting + globbing)

# BAD: word splits and globs if file contains spaces or wildcards
for f in $files; do rm $f; done

# GOOD: always quote variable expansions
for f in "${files[@]}"; do rm "$f"; done

[ ] vs [[ ]]

# BAD: word splitting inside [ ] can break with spaces in $var
[ $var == "hello" ]          # also: == is not POSIX in [ ]

# GOOD: [[ ]] prevents word splitting and supports == and =~
[[ $var == "hello" ]]

$@ vs $* quoting

# BAD: loses word boundaries
for arg in $@; do echo "$arg"; done

# GOOD: preserves each argument as a separate word
for arg in "$@"; do echo "$arg"; done

# "$*" joins all args into ONE word (separated by first char of IFS)

set -e doesn't trigger everywhere

set -e
# These do NOT cause exit on failure:
if false; then :; fi           # test in 'if'
false || true                  # LHS of ||
false && true                  # LHS of &&
false | true                   # pipeline (without pipefail)
! false                        # negated command

Missing ; before } in brace groups

# BAD: syntax error
{ echo "hello" }

# GOOD: semicolon (or newline) required before }
{ echo "hello"; }

Array access without braces

arr=(one two three)

# BAD: expands $arr (element 0) then appends literal [1]
echo $arr[1]      # prints: one[1]

# GOOD: braces required for array subscript
echo "${arr[1]}"  # prints: two

Forgetting declare -A for associative arrays

# BAD: creates an indexed array, keys treated as arithmetic (0)
map=([foo]=1 [bar]=2)
echo "${map[foo]}"  # prints: 2 (both keys evaluated to index 0)

# GOOD: must declare associative arrays explicitly
declare -A map=([foo]=1 [bar]=2)
echo "${map[foo]}"  # prints: 1

Using = vs == in the wrong context

# In [ ] / test: use = (POSIX). == works in Bash but is not portable.
[ "$a" = "$b" ]

# In [[ ]]: both = and == work; RHS is a pattern (quote for literal match)
[[ "$a" == "$b" ]]      # literal match (RHS quoted)
[[ "$a" == "$b"* ]]     # glob pattern (unquoted * appended)
[[ "$a" == $b ]]        # if $b contains *, it's a pattern (RHS unquoted)

Subshell variable loss in pipes

# BAD: read runs in subshell, $var is lost after pipeline
echo "hello" | read var
echo "$var"    # empty

# GOOD: use process substitution or lastpipe
read var < <(echo "hello")
echo "$var"    # hello

# OR: enable lastpipe (non-interactive, no job control)
shopt -s lastpipe
echo "hello" | read var

local variables use dynamic scoping

inner() { echo "$x"; }
outer() { local x=42; inner; }
outer  # prints: 42 (inner sees outer's local!)

# This is dynamic scoping, not lexical. Any function called
# from a scope with a local variable sees that variable.

Here-strings always append a trailing newline

read -r var <<< "hello"
printf '%s' "$var" | xxd  # contains "hello\n" — trailing newline added
# Use printf instead when exact bytes matter:
read -r var < <(printf '%s' "hello")

declare -i silently evaluates strings as arithmetic

declare -i num
num="1+1"
echo "$num"  # prints: 2 (string was evaluated!)
# WARNING: with untrusted input this is a code injection vector:
# declare -i x; x="a]$(cmd)" would execute cmd

trap EXIT is reset in subshells

trap 'echo cleanup' EXIT
(echo "subshell")  # EXIT trap does NOT fire here
# Subshells inherit the parent's traps but reset EXIT/ERR/DEBUG/RETURN.
# If you need cleanup in a subshell, set a new trap inside it.