Bash Cheatsheet — 100+ Commands and Idioms for Shell Scripting on Linux and macOS

Assign a variable. NO spaces around `=` — `name = value` is a command call, not an assignment.

⚠ Common pitfall: `x = 1` calls a program named `x` with args `=` and `1`. Bash will say `x: command not found` and you will spend ten minutes wondering why.

name="Lei Li"

count=42

today=$(date +%F)

Mark a variable for export to child processes. Without `export`, the variable stays in the current shell only.

export PATH="$HOME/bin:$PATH"

export EDITOR=vim

Quoted expansion with explicit braces. The braces let you stick text right after the variable name without ambiguity.

⚠ Common pitfall: Without braces, `$prefix_v1` looks like the variable `prefix_v1`, not `$prefix` followed by `_v1`. Write `"${prefix}_v1"`.

echo "Hello, ${name}!"

file="${base}_${date}.log"

Use $var if set and non-empty; otherwise substitute `default`. Does NOT modify $var.

port="${PORT:-8080}"

name="${1:-world}"   # default first arg

Same as `:-` but also ASSIGNS the default back into $var. Does not work on positional args ($1, $2…).

: "${LOG_DIR:=/var/log/app}"   # ensure LOG_DIR is set

If $var is unset or empty, print the message to stderr and exit. Great as a hard guard at the top of a script.

: "${API_KEY:?need to set API_KEY in env}"

If $var is set and non-empty, substitute `alt`; otherwise substitute nothing. Useful for "only add this flag if X was set".

args="${DEBUG:+--verbose}"   # add --verbose only if DEBUG is set

Replace EVERY occurrence of `old` with `new` in $var. Single slash replaces only the first.

path="${path//\\//}"   # backslashes to forward slashes

safe="${name// /_}"

Strip the shortest (#) or longest (##) matching `prefix` from the front of $var. Patterns are globs, not regex.

file=/path/to/file.tar.gz

echo "${file##*/}"   # file.tar.gz

echo "${file#*/}"    # path/to/file.tar.gz

Strip the shortest (%) or longest (%%) matching `suffix` from the end of $var. Mirror of # and ##.

file=archive.tar.gz

echo "${file%.gz}"     # archive.tar

echo "${file%%.*}"     # archive

Length (in characters) of $var.

s="hello"

echo "${#s}"   # 5

Substring of $var: skip `start` chars, take `length` chars. Both numbers can be expressions.

s="abcdefgh"

echo "${s:2:3}"   # cde

echo "${s:(-3)}"  # fgh (last 3)

Upper-case (^^) or lower-case (,,) all characters of $var. Bash 4+ only.

⚠ Common pitfall: macOS ships Bash 3.2 (license reasons). On macOS you need `brew install bash` to get 4+, or fall back to `tr`.

s="hello"

echo "${s^^}"   # HELLO

echo "${s,,}"   # hello (already)

Bash built-in that yields a random integer 0–32767 each time it is referenced.

echo $RANDOM

echo $((RANDOM % 100))   # 0-99

tmp="/tmp/job-$RANDOM"

Declare a constant — any later assignment to NAME will fail. Use for config you really do not want overwritten.

readonly VERSION=1.2.3

readonly LOG_DIR=/var/log/app

Delete a variable entirely. After `unset x`, both `$x` and `${x:-}` expand to empty.

unset TMPDIR

unset -f my_function   # also unsets a function

Bash conditional. Prefer `[[ ]]` over the older `[ ]` — it handles spaces, regex, and globbing without surprises.

if [[ -f config.yaml ]]; then echo "found"; fi

if [[ "$user" == "root" ]]; then echo "boss"; fi

String equality. `==` and `=` both work inside `[[ ]]`. Always quote the right side unless you want glob matching.

⚠ Common pitfall: Inside `[[ ]]`, an UNQUOTED right side becomes a glob: `[[ $f == *.log ]]` matches any file ending in .log. Quote it to compare literally.

if [[ "$name" == "alice" ]]; then ... fi

if [[ "$file" == *.log ]]; then ...   # glob match, no quotes

String inequality. Symmetric to `==`.

if [[ "$env" != "prod" ]]; then echo "safe to delete"; fi

Regex match. The regex is bash ERE; captures land in BASH_REMATCH.

⚠ Common pitfall: Do NOT quote the regex — quoting turns metacharacters into literals. `[[ $s =~ "^[0-9]+$" ]]` matches the literal string, not digits.

if [[ "$ip" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then echo "looks like ipv4"; fi

if [[ "$s" =~ ^([a-z]+)=([0-9]+)$ ]]; then echo "${BASH_REMATCH[1]}=${BASH_REMATCH[2]}"; fi

Arithmetic comparison. Use `(( ))` for numeric work — `<`, `>`, `==`, `!=`, `<=`, `>=` all behave like C.

if (( count > 10 )); then echo "many"; fi

if (( a + b == 100 )); then echo "match"; fi

POSIX-style numeric test inside `[[ ]]`. Operators: -lt -le -gt -ge -eq -ne. Use these when comparing numbers as strings.

⚠ Common pitfall: `[[ "5" > "10" ]]` is TRUE — string comparison says "5" sorts after "1". Use `-gt` or `(( 5 > 10 ))` for numeric intent.

if [[ "$age" -ge 18 ]]; then echo "adult"; fi

File tests. -f: regular file. -d: directory. -e: any path exists (file, dir, socket, link target). -L: symlink.

[[ -f /etc/hosts ]] && echo "exists"

[[ -d "$HOME/.config" ]] || mkdir -p "$HOME/.config"

[[ -e /tmp/lock ]] && exit 1

-z: string is empty (zero length). -n: string is non-empty.

⚠ Common pitfall: ALWAYS quote: `[[ -z $s ]]` breaks if $s contains spaces. `[[ -z "$s" ]]` is safe.

[[ -z "$NAME" ]] && NAME="anon"

if [[ -n "$DEBUG" ]]; then set -x; fi

Short-circuit chain. && runs the next command only if the previous succeeded (exit 0); || only if it failed.

⚠ Common pitfall: `cmd && a || b` is NOT `if cmd then a else b`. If `a` itself fails, `b` runs too. Use a real `if` for branching.

ping -c1 host && echo "up" || echo "down"

[[ -d build ]] || mkdir build

Negate a command exit status. `!` flips success/failure for use in `if` / `while`.

if ! grep -q "ok" status.log; then echo "missing ok line"; fi

while ! curl -fs http://app/health; do sleep 1; done

Multi-way branch on glob patterns. Cheaper and clearer than a tower of elif when matching strings.

case "$1" in
  start) start_service ;;
  stop)  stop_service ;;
  *)     echo "usage: $0 start|stop"; exit 1 ;;
esac

Logical AND inside a single `[[ ]]`. Use `&&` (not `-a`) — `[[ ]]` is bash, not POSIX test.

if [[ -f config && -r config ]]; then echo "readable"; fi

Loop over a literal list of words. Each iteration assigns one word to $x.

for env in dev staging prod; do
  echo "deploying $env"
done

Loop over filenames matching a glob. Handles spaces correctly — no word-splitting on whitespace inside filenames.

⚠ Common pitfall: If no files match, the glob expands to the literal pattern `*.log` and your loop body sees `f="*.log"`. Guard with `shopt -s nullglob` to skip the loop on no matches.

shopt -s nullglob

for f in *.log; do
  gzip "$f"
done

C-style for loop. Use for indexed iteration when you need the counter itself.

for ((i=1; i<=5; i++)); do
  echo "attempt $i"
done

Iterate over words from command output. Output is split on $IFS (default: spaces, tabs, newlines).

⚠ Common pitfall: Filenames with spaces break this. Prefer `while read -r line` with redirection for lines, or set IFS=$'\n' for newline-only splitting.

for pid in $(pgrep nginx); do
  echo "nginx pid: $pid"
done

Read a file line by line, safely. `-r` disables backslash escapes; the < at the end feeds the loop without subshell traps.

⚠ Common pitfall: If you write `cat file | while read line`, the loop runs in a subshell and variables you set inside DIE when the loop ends. Use `done < file` instead.

while read -r line; do
  echo "got: $line"
done < urls.txt

Loop while a condition stays true. Common for retry loops and queue draining.

attempts=0

while ! curl -fs http://app/health; do
  ((attempts++))
  (( attempts > 30 )) && exit 1
  sleep 1
done

Loop UNTIL the condition becomes true (i.e. while it is false). Symmetric to `while`.

until ping -c1 -W1 host >/dev/null 2>&1; do sleep 1; done

`break` exits the innermost loop right now. `continue` skips to the next iteration. `break 2` exits two levels.

for f in *; do
  [[ -d "$f" ]] || continue
  [[ "$f" == "stop" ]] && break
  echo "$f"
done

Interactive numbered menu. Bash prints the choices, the user picks a number, $x gets the value. Loops until you `break`.

select env in dev staging prod quit; do
  [[ "$env" == "quit" ]] && break
  echo "you chose $env"
done

Brace expansion gives a numeric range. {1..10..2} skips by 2. Expanded BEFORE variable substitution.

⚠ Common pitfall: `{1..$n}` does NOT work because brace expansion happens before $n is read. Use `seq $n` or a C-style for loop.

for i in {1..5}; do echo "$i"; done

for i in {0..100..10}; do echo "$i"; done

Parse a CSV line by line: set IFS to comma, then read splits the line into named fields.

while IFS=, read -r name age role; do
  echo "$name ($age) is a $role"
done < team.csv

Define a function. The `function` keyword is optional in bash; the POSIX form `name()` is more portable.

greet() {
  echo "Hello, $1!"
}

greet "Lei"   # → Hello, Lei!

Bash-only function form. Identical to `name() { ... }` but with the keyword.

function deploy {
  echo "deploying $1 to $2"
}

Positional arguments inside a function or script. $1 is the first, $0 is the script/function name.

⚠ Common pitfall: Two-digit args need braces: `$10` reads as `$1` followed by literal `0`. Use `${10}` for the tenth arg.

copy() {
  cp "$1" "$2"
}

"$@" preserves each argument as a separate word (the usual right answer). "$*" joins them with the first char of $IFS.

⚠ Common pitfall: Without quotes, both behave the same — and both break on spaces. ALWAYS use the quoted form `"$@"` when forwarding args.

run_with_logging() {
  echo "[$(date)] running: $*"
  "$@"
}

Declare a function-local variable. Without `local`, every assignment in a function pollutes the global scope.

greet() {
  local who="$1"
  echo "Hello, $who"
}

Set the function exit status. 0 = success, 1-255 = failure. NOT the same as a function "return value" — for data use stdout + $(fn).

is_valid() {
  [[ "$1" =~ ^[0-9]+$ ]] && return 0 || return 1
}

if is_valid "$x"; then echo ok; fi

Capture function output. Functions return data the same way commands do: print to stdout, caller wraps in $(...).

get_timestamp() { date +%s; }

now=$(get_timestamp)

echo "now is $now"

Print the definition of a function. `declare -F` lists names only. Useful for debugging which version of a function is loaded.

declare -f greet

declare -F | head   # list all defined functions

Redirect stdout to file, OVERWRITING. Use `>>` to append instead.

ls > files.txt

date >> log.txt   # append

Redirect stderr (fd 2) to file. stdout still goes to the terminal.

make 2> build-errors.log

cmd 2>/dev/null   # discard errors

Redirect BOTH stdout and stderr to the same file. Order matters: first redirect stdout, THEN dup stderr to wherever stdout now points.

⚠ Common pitfall: `cmd 2>&1 > file` does NOT work — stderr is duped to the terminal first, then stdout is moved to file. Always put `2>&1` AFTER `> file`.

build.sh > build.log 2>&1

cmd &> file   # bash shortcut for the same thing

Bash shortcut: redirect both stdout AND stderr to file. Equivalent to `> file 2>&1`.

⚠ Common pitfall: `&>` is bash-specific. POSIX sh does not understand it — for portable scripts use `> file 2>&1`.

./test.sh &> test.log

Feed file as stdin to cmd. Same as `cat file | cmd` but without the extra cat process.

mysql -u root db < schema.sql

while read -r line; do echo "$line"; done < input.txt

Here-document: feed multi-line literal text as stdin. The marker (EOF here) just has to be unique on its own line.

cat <<EOF > config.yaml
name: app
port: 8080
EOF

Quoted heredoc — single-quoting the marker DISABLES variable and command substitution inside. The body is fully literal.

cat <<'EOF'
This $will not expand and `nor will this`.
EOF

Here-string: feed a single string as stdin. Cleaner than `echo "$var" | cmd` for one-liners.

grep -c "ERROR" <<< "$log"

tr a-z A-Z <<< "hello"

Redirect the SCRIPT's own stdout from this line on. After this, every command in the script writes to `file` instead of the terminal.

#!/bin/bash
exec > script.log 2>&1
echo "this goes to script.log"

# tee pattern:
exec > >(tee script.log) 2>&1

Throw stderr away. Useful when a command spews known noise — e.g. `find` complaining about permission-denied dirs.

⚠ Common pitfall: Hiding errors hides real bugs. Use sparingly and prefer filtering specific patterns: `cmd 2> >(grep -v "expected noise" >&2)`.

find / -name foo 2>/dev/null

which gcc &>/dev/null && echo "have gcc"

Pipe: stdout of cmd1 becomes stdin of cmd2. Each command runs in its own subprocess in parallel.

ps aux | grep nginx

cat access.log | awk '{print $7}' | sort | uniq -c | sort -rn

Pipe both stdout AND stderr into cmd2. Bash 4+ shortcut for `cmd1 2>&1 | cmd2`.

make |& tee build.log

Run cmd in the background. Returns immediately with the PID in $!. `wait` blocks until all background jobs finish.

long_task &

pid=$!

# do other work

wait $pid

Command substitution: replace with cmd's stdout. Preferred over backticks because $(...) NESTS cleanly.

⚠ Common pitfall: Trailing newlines are STRIPPED. If you care about preserving them, append a sentinel: `out=$(cmd; echo END)`.

today=$(date +%F)

count=$(grep -c ERROR app.log)

files=$(find . -name "*.py" | head -5)

Old-style command substitution. Works but does NOT nest cleanly and quoting gets ugly. Prefer `$(cmd)`.

date=`date +%F`   # works but legacy

echo "Today: $(date +%F)"   # better

Process substitution: makes cmd's output look like a temp filename. Lets you pass "streams" where a tool expects file arguments.

⚠ Common pitfall: Process substitution is bash, not POSIX sh. The `<(...)` syntax errors out under dash / busybox sh.

diff <(sort a.txt) <(sort b.txt)

comm -12 <(sort users-old) <(sort users-new)

Make a pipeline fail if ANY command in the pipe fails. Without this, only the LAST command's exit code is reported.

set -euo pipefail

curl -fsS bad-url | jq .   # without pipefail, jq exit 0 hides curl failure

Pipe to file AND keep printing to stdout. Add `-a` to append instead of overwrite.

make 2>&1 | tee build.log

echo "192.168.1.1 host" | sudo tee -a /etc/hosts

Run a group in a SUBSHELL. Variables you set inside do NOT leak out — useful for scoping `cd`, `set -x`, env tweaks.

( cd /tmp && tar xzf "$tarball" )   # the parent shell stays where it was

Run a group in the CURRENT shell (no subshell). Variables persist after the group. Needs spaces and trailing semicolon.

{ echo "header"; cat file; echo "footer"; } > out.txt

Byte length of $var (use `${#var}` for character length in single-byte locales).

⚠ Common pitfall: `${#var}` counts characters not bytes — a Chinese character may be 1 in count but 3 bytes in UTF-8. `wc -c` counts bytes; `wc -m` counts characters in the current locale.

s="hello"

echo "${#s} chars"

echo -n "$s" | wc -c

Split a string by a delimiter into an array. `-a parts` reads into the indexed array `parts`.

IFS=":" read -ra dirs <<< "$PATH"

for d in "${dirs[@]}"; do echo "$d"; done

Assign formatted output directly to a variable — no subshell, no command substitution overhead.

printf -v fname "report-%s-%02d.csv" "$dept" "$month"

echo "$fname"   # report-sales-05.csv

Replace all spaces with underscores. Single slash replaces only the first match.

name="hello world"

safe="${name// /_}"

echo "$safe"   # hello_world

Test if a string starts with a prefix using glob in `[[ ]]`. Suffix is `*prefix`.

if [[ "$file" == /etc/* ]]; then echo "system config"; fi

if [[ "$url" == https://* ]]; then ...; fi

Upper-case a string portably (works on bash 3.2 macOS). tr does character translation.

upper=$(tr "a-z" "A-Z" <<< "$name")

echo "$upper"

Exit immediately if any command returns non-zero. The "fail fast" flag — combine with -u and -o pipefail for safe scripts.

⚠ Common pitfall: set -e is FULL of corner cases. `cmd1 && cmd2` does NOT trigger -e if cmd1 fails. `cmd || true` is the idiom for "I expect this to fail sometimes".

set -euo pipefail

IFS=$'\n\t'   # the "unofficial bash strict mode" header

Treat unset variables as errors. Catches typos like `$ptah` vs `$path` immediately instead of silently expanding to "".

⚠ Common pitfall: With -u, `${var}` errors out if unset. Always use `${var:-}` for "I know it might be unset" and `${var:?msg}` to assert it must be set.

set -u

echo "$undefined"   # bash: undefined: unbound variable

Print every command (with expanded variables) before running it. The fastest way to debug a script.

set -x

name="lei"

echo "hello $name"

# stderr: + name=lei
#         + echo 'hello lei'

A pipeline's exit code is the rightmost FAILING command, not just the last command. Pairs with -e.

set -o pipefail

curl bad-url | jq .   # now fails properly when curl fails

Run `cleanup` when the script exits, no matter how (normal, error, signal). The standard pattern for tmpfile cleanup.

tmp=$(mktemp)

trap "rm -f \"$tmp\"" EXIT

# tmp gets removed even if the script crashes

Intercept Ctrl-C (INT) and `kill` (TERM). Print a message, do cleanup, then exit gracefully.

trap "echo '^C — bye'; exit 130" INT

trap "stop_server; exit" TERM

Terminate the script with exit code N. 0 = success. By convention 1 = generic error, 2 = misuse, 127 = command not found.

exit 0

exit 1   # generic failure

[[ $# -eq 0 ]] && { echo "need an arg"; exit 2; }

Exit status of the LAST command. Read it ONCE — every later command (including `[ ]`) updates it.

⚠ Common pitfall: `cmd; if [[ $? -eq 0 ]]; then echo "ok"; fi` is over-engineered. Just write `if cmd; then echo "ok"; fi`.

ping -c1 host >/dev/null

rc=$?

echo "ping returned $rc"

Print how long cmd took (real, user, sys). Built-in to bash; works on pipelines too.

time make build

time (find /usr | wc -l)

Shebang line. `env bash` finds bash on $PATH instead of hard-coding /bin/bash (which on macOS is the ancient 3.2 build).

#!/usr/bin/env bash

set -euo pipefail

IFS=$'\n\t'

POSIX-portable option parsing. `:` after a letter means it takes an argument (in $OPTARG); leading `:` enables silent error handling.

while getopts ":hf:v" opt; do
  case $opt in
    h) echo "usage: ..."; exit 0 ;;
    f) file="$OPTARG" ;;
    v) verbose=1 ;;
    \?) echo "bad flag: -$OPTARG" >&2; exit 2 ;;
  esac
done

shift $((OPTIND - 1))   # consume parsed flags

Hand-rolled arg parsing for long options (--flag value, --flag=value). More flexible than getopts but you write more code.

while [[ $# -gt 0 ]]; do
  case "$1" in
    --port)  port="$2"; shift 2 ;;
    --port=*) port="${1#*=}"; shift ;;
    --) shift; break ;;
    *) args+=("$1"); shift ;;
  esac
done

Create a guaranteed-unique temp file and arrange to delete it on exit. Use `mktemp -d` for a temp directory.

⚠ Common pitfall: BSD mktemp (macOS) needs a template: `mktemp /tmp/myapp.XXXXXX`. GNU mktemp works without one. `mktemp -t prefix` is the portable form.

tmp=$(mktemp)

trap "rm -f \"$tmp\"" EXIT

curl -o "$tmp" https://example.com/data.json

Print colored text via ANSI escape codes. \033[31m = red, \033[0m = reset. Only when output is a TTY (test with `[[ -t 1 ]]`).

RED=$'\033[31m'

RESET=$'\033[0m'

[[ -t 1 ]] || RED='' RESET=''   # disable colors when piped

echo "${RED}ERROR${RESET}: bad config"

A poor-man's progress bar. \r returns the cursor to the line start so each update overwrites the previous one.

for i in {1..100}; do
  pct=$i
  bar=$(printf "%.0s#" $(seq 1 $((pct/2))))
  printf "\r[%-50s] %3d%%" "$bar" "$pct"
  sleep 0.05
done
echo

Script's own invocation name. Useful for usage strings: `echo "usage: $0 [options]"`.

if [[ $# -lt 2 ]]; then
  echo "usage: $0 <src> <dst>" >&2
  exit 2
fi

Resolve the script's own directory, even when called through symlinks. The standard "find my siblings" idiom.

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

source "$SCRIPT_DIR/lib.sh"

Check whether a command exists without running it. Returns 0 if found. More portable than `which`.

if ! command -v jq >/dev/null; then
  echo "need jq, please install" >&2
  exit 1
fi

Prompt the user and read one line into $ans. -p sets the prompt; -s hides input (for passwords).

read -p "Continue? [y/N] " ans

[[ "${ans,,}" == "y" || "${ans,,}" == "yes" ]] || exit 0

Cheap timestamped log helper that writes to stderr (so it does not pollute pipeline output).

log() { echo "[$(date +%H:%M:%S)] $*" >&2; }

log "starting deploy"

log "done"

Declare an indexed (numeric-key) array. Bash arrays are 0-indexed.

declare -a fruits=(apple banana cherry)

echo "${fruits[0]}"   # apple

Declare an associative array (string keys). Bash 4+ only. macOS Bash 3.2 does NOT support these.

⚠ Common pitfall: You MUST `declare -A map` before using it. Otherwise `map["key"]="v"` silently treats `"key"` as 0 and you get an indexed array with one element.

declare -A color

color[apple]=red

color[grape]=purple

echo "${color[apple]}"   # red

Initialize an indexed array literally. Space-separated, parens around.

envs=(dev staging prod)

echo "${envs[1]}"   # staging

Append elements to the end of an indexed array.

files=()

for f in *.log; do files+=("$f"); done

echo "${#files[@]} log files"

Expand to ALL elements as separate quoted words. The usual right way to iterate.

⚠ Common pitfall: `"${arr[*]}"` joins everything into ONE string with $IFS. Almost always you want `"${arr[@]}"` instead.

for f in "${files[@]}"; do
  echo "$f"
done

Number of elements in the array.

echo "${#files[@]} files matched"

if (( ${#errors[@]} > 0 )); then echo "had errors"; fi

Expand to all KEYS of the array (indices for indexed arrays, string keys for associative).

for i in "${!arr[@]}"; do
  echo "$i -> ${arr[$i]}"
done

for k in "${!color[@]}"; do
  echo "$k is ${color[$k]}"
done

Remove a single element. Indices are NOT renumbered — `${#arr[@]}` shrinks but `${arr[3]}` is still there.

arr=(a b c d)

unset "arr[1]"

echo "${arr[@]}"   # a c d

echo "${!arr[@]}"   # 0 2 3

Read every line of a file into an array, one line per element. `-t` strips the trailing newline from each line.

mapfile -t lines < urls.txt

echo "read ${#lines[@]} urls"

Unquoted variable expansion goes through word-splitting (split on $IFS) AND glob expansion. A filename with spaces or a glob char becomes multiple arguments.

⚠ Common pitfall: `rm $file` with file="report 2024.csv" becomes `rm report 2024.csv` — two args. `rm "$file"` is the safe form. Default to quoting; un-quote only when you specifically want splitting.

cp "$src" "$dst"   # safe

for f in "$@"; do echo "$f"; done   # safe

`cd /missing/dir; rm -rf *` deletes the CURRENT directory if cd fails. Always chain: `cd dir && rm ...` or check `cd || exit`.

⚠ Common pitfall: set -e does NOT help with this — `cd` failing followed by `;` rm runs anyway. Use && or `cd dir || { echo "no such dir" >&2; exit 1; }`.

cd "$build_dir" && rm -rf *   # safe

pushd "$dir" || exit; do_work; popd

`cat file | while read line; do count=$((count+1)); done` — $count is 0 after the loop because while ran in a subshell. Use `done < file` or process substitution.

# wrong:
# cat file | while read l; do n=$((n+1)); done
# right:
while read -r l; do n=$((n+1)); done < file
echo "$n"

set -e ignores failures inside `if`, `while`, `until`, `&&`, `||`, and pipelines (without pipefail). It only kills on bare commands at the top level.

⚠ Common pitfall: Add `set -o pipefail` and never rely on -e as your only safety net. Explicit checks (`|| { echo err; exit 1; }`) are the real defense.

set -euo pipefail

critical_cmd || { echo "critical failed" >&2; exit 1; }

A glob with no matches expands to the LITERAL pattern, not an empty list. `for f in *.log` with no logs iterates once with f="*.log".

⚠ Common pitfall: Fix with `shopt -s nullglob` (no-match → empty list) or `shopt -s failglob` (no-match → error). Pick once per script and stick with it.

shopt -s nullglob

for f in *.log; do echo "$f"; done

`wc -l` counts NEWLINE characters, not lines. A file ending without \n loses its last line in the count.

⚠ Common pitfall: Use `awk "END{print NR}"` for a true line count, or `grep -c ""` which counts records including the unterminated one.

printf "a\nb" | wc -l   # 1 (!)

printf "a\nb" | awk "END{print NR}"   # 2

`[[ "5" > "10" ]]` is TRUE because it does ASCII comparison. For numbers use `(( 5 > 10 ))` or `[[ 5 -gt 10 ]]`.

(( age >= 18 ))   # numeric

[[ "$name" > "alice" ]]   # alphabetic

In a sourced script, `$0` is the SHELL's name (bash, zsh), not the script's. Use `${BASH_SOURCE[0]}` to get the actual file path.

# inside lib.sh:
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
  echo "run directly"
else
  echo "sourced from $0"
fi

Apple ships bash 3.2 (May 2007) because newer versions are GPLv3-licensed. Associative arrays, ${var^^}, mapfile, |& all need bash 4+.

⚠ Common pitfall: `brew install bash` then put `/opt/homebrew/bin/bash` in your shebang. Or change to zsh, which is default on modern macOS.

bash --version   # check yours

#!/opt/homebrew/bin/bash   # macOS modern bash

Parentheses `(...)` run in a subshell — variable assignments and `cd` inside do NOT affect the parent shell.

x=outer

(x=inner; echo "in: $x")   # in: inner

echo "out: $x"             # out: outer

Built-in `getopts` only handles single-char flags like `-f file`. For `--file file` you need `getopt` (note: no s — different program) or hand-rolled parsing.

⚠ Common pitfall: GNU getopt and BSD getopt are incompatible. macOS getopt is the original BSD one — no long-option support. For cross-platform long flags, hand-roll the loop.

# portable long-option parsing:
while [[ $# -gt 0 ]]; do
  case "$1" in
    --file) file="$2"; shift 2 ;;
    --) shift; break ;;
    *) shift ;;
  esac
done