Coding 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 bitranox:coding-bash-clean-architecture instead)

Before you reach for Bash (and before you ship)

• Prefer a Python script over shell for any real logic (global working rule). Shell has sharp edges that bite repeatedly - a leading-dash path makes dirname/grep treat it as an option, sed -i can double-apply, and cmd | head reports head's exit status not cmd's. For path handling, text transforms, or multi-step automation, write a Python (stdlib) script. Reserve Bash for a simple one-shot command invocation (including launching a Python script).
• Gate every Bash script you DO ship with shellcheck and bash -n before committing - required checks, not optional. shellcheck -x script.sh (follows sourced files) catches quoting, word-splitting, and unset-variable bugs; bash -n script.sh catches syntax errors without executing it. Add shfmt -i 4 -d script.sh where the project formats shell.

Reference Files

Which File Do I Need?

Quick Reference: Most-Used Constructs

Quoting

Full details: shell-syntax-and-commands.md (section 3.1.2, Quoting)

Parameter Expansion

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

Special Parameters

Full details: functions-parameters-expansions.md (section 3.4.2, Special Parameters)

Compound Commands

Full details: shell-syntax-and-commands.md (section 3.2.5, Compound Commands)

# 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 6.4, Bash Conditional Expressions)

Redirections

Full details: redirections-and-execution.md (section 3.6, Redirections)

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.7, Arrays)

# 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 4.3.1, the set builtin)

Essential shopt Options

Full details: shell-builtins.md (section 4.3.2, the shopt builtin)

Trap Signals

Full details: shell-builtins.md (section 4.1, the trap builtin) and redirections-and-execution.md (section 3.7.6, 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 6.5, Shell Arithmetic)

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

Bases: 0x (hex), 0 (octal), base#number (arbitrary base 2-64, e.g. 2#101 for binary). Bash has no 0b binary prefix.

Prompt Escape Sequences

Full details: bash-features.md (section 6.9, 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 (<<<) add a trailing newline to the stream

cat <<< "hello" | od -An -tx1   # 68 65 6c 6c 6f 0a  <- <<< appended a newline
wc -c <<< "hello"               # 6 bytes, not 5
# read strips the delimiter, so $var does NOT keep that newline:
read -r var <<< "hello"
printf '%s' "$var" | od -An -tx1  # 68 65 6c 6c 6f  (no trailing newline)
# For exact bytes with no newline, feed read from printf:
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

For handling untrusted input at a script/CLI boundary in general (validate at the edge, never eval it, pass argv not a shell string, escape per sink), see bitranox:coding-input-sanitization.

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.