bx-bash-reference

name: bx-bash-reference description: Use when writing, reviewing, or debugging Bash scripts, when needing exact syntax for shell constructs, parameter expansions, redirections, builtins, test expressions, arrays, or any Bash 5.3 feature. Use when unsure about quoting rules, expansion order, conditional operators, trap behavior, shopt options, or specific builtin options and arguments.

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

Which File Do I Need?

Quick Reference: Most-Used Constructs

Quoting

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

Parameter Expansion

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

Special Parameters

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

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)

Redirections

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

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)

Essential shopt Options

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

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)

Definitions

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.