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

Replace only the FIRST occurrence of `old` with `new`. Double slash `//` replaces all.

p="a.b.c"

echo "${p/./_}"   # a_b.c

echo "${p//./_}"  # a_b_c

Anchored replace: `/#` only matches at the START of the string, `/%` only at the END.

s="test.log"

echo "${s/#test/prod}"   # prod.log

echo "${s/%.log/.txt}"   # test.txt

Indirect: expand to the NAMES of all variables whose name starts with `prefix`. Handy for config introspection.

APP_HOST=a; APP_PORT=b

for v in "${!APP_@}"; do echo "$v=${!v}"; done

Indirect expansion: if `ref=path`, then `${!ref}` expands to the value of $path. One level of pointer.

path="/usr/bin"

ref="path"

echo "${!ref}"   # /usr/bin

Mark a variable as integer. Assignments are then evaluated as arithmetic; `num=2+3` stores 5, not the string.

declare -i n

n="3 * 4"

echo "$n"   # 12

Declare a read-only variable. Same effect as `readonly` but in the unified `declare` syntax.

declare -r MAX=100

MAX=200   # bash: MAX: readonly variable

Slice positional parameters: take `count` args starting from position `start`. `${@:2}` drops the first arg.

# args: a b c d

echo "${@:2}"     # b c d

echo "${@:2:2}"   # b c

Nameref: make `ref` an alias for the variable named in `name`. Lets a function write to a caller variable. Bash 4.3+.

fill() { local -n out=$1; out=(x y z); }

fill result

echo "${result[@]}"   # x y z

Major version of the running bash as an integer. Gate features without parsing $BASH_VERSION strings.

if (( BASH_VERSINFO[0] < 4 )); then
  echo "need bash 4+" >&2; exit 1
fi

$LINENO is the current line number; $FUNCNAME[0] is the running function name. Build precise log/error prefixes with them.

die() { echo "[$FUNCNAME:${BASH_LINENO[0]}] $*" >&2; exit 1; }

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

True if file1 is NEWER THAN file2 (by modification time), or file1 exists and file2 does not. `-ot` is older-than.

if [[ src.c -nt build/src.o ]]; then
  echo "need rebuild"
fi

Permission tests for the current user: -r readable, -w writable, -x executable (or searchable for a dir).

[[ -x "$(command -v git)" ]] && echo "git runnable"

[[ -w /etc/hosts ]] || echo "need sudo to edit hosts"

True if file exists AND has size greater than zero. The clean way to check "did the output actually get written".

curl -o out.json "$url"

[[ -s out.json ]] || { echo "empty download" >&2; exit 1; }

True if file descriptor 1 (stdout) is attached to a terminal. Use it to enable colors only when not piped/redirected.

if [[ -t 1 ]]; then COLOR=1; else COLOR=0; fi

True if `var` is SET (even if empty). Distinguishes "unset" from "set to empty string". Bash 4.2+.

x=""

[[ -v x ]] && echo "x is set (but empty)"

[[ -v y ]] || echo "y is unset"

A single case branch can match several patterns with `|`. Cleaner than repeating branches.

case "$ans" in
  y|Y|yes) proceed ;;
  n|N|no)  abort ;;
  *)       echo "?" ;;
esac

Make `[[ ]]` and `case` matching case-INSENSITIVE for the rest of the shell. Turn it back off with `shopt -u`.

shopt -s nocasematch

[[ "HELLO" == hello ]] && echo "match"

shopt -u nocasematch

Lexicographic (dictionary order) string comparison inside `[[ ]]`. Sorts by the current locale collation.

⚠ Common pitfall: In `[[ ]]`, `<` and `>` are string operators and need no escaping. In `[ ]` (single bracket) you must write `\<` or it becomes redirection.

[[ "apple" < "banana" ]] && echo "apple first"

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

Loop a runtime-computed number of times. Use `seq` when the count comes from a variable (brace `{1..$n}` will not expand).

n=5

for i in $(seq 1 "$n"); do echo "$i"; done

Infinite loop. `:` is the built-in no-op that always returns true. Exit with `break` or a guarded condition inside.

while :; do
  read -r line || break
  echo "got: $line"
done

Loop over SUBDIRECTORIES only. The trailing slash makes the glob match directories (and symlinks to dirs).

for d in /var/log/*/; do
  echo "dir: ${d%/}"
done

Read splits each line into fields by $IFS; the LAST named variable soaks up everything remaining. Great for "first two columns + rest".

while read -r user uid rest; do
  echo "$user has uid $uid"
done < <(getent passwd)

Iterate find results SAFELY for any filename. -print0 separates with NUL; -d "" reads up to NUL. Handles spaces and newlines in names.

⚠ Common pitfall: A plain `for f in $(find ...)` breaks on spaces and newlines in filenames. The NUL-delimited pattern is the robust one.

find . -name "*.tmp" -print0 | while IFS= read -r -d "" f; do
  rm -- "$f"
done

Iterate an array element by element, quote-safe. Each element stays one word even with embedded spaces.

files=("a b.txt" "c.txt")

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

`continue N` skips to the next iteration of the N-th ENCLOSING loop. `continue 2` jumps the outer loop forward.

for i in 1 2 3; do
  for j in a b c; do
    [[ "$j" == b ]] && continue 2
    echo "$i$j"
  done
done

Start a co-process: cmd runs in the background with its stdin/stdout wired to file descriptors in ${NAME[1]} / ${NAME[0]}.

coproc BC { bc -l; }

echo "2^10" >&"${BC[1]}"

read -r ans <&"${BC[0]}"

echo "$ans"   # 1024

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

Declare a function-local array (-a indexed, -A associative). Keeps array state from leaking to the global scope.

parse() {
  local -a parts
  IFS=: read -ra parts <<< "$1"
  echo "${#parts[@]} fields"
}

Drop the first positional argument (or first N). After `shift`, $1 becomes the old $2 and $# drops by one.

cmd="$1"; shift

echo "running $cmd with: $*"

Reset the positional parameters ($1, $2, …) to the given values. `set --` with nothing clears them all.

set -- one two three

echo "$1 $3"   # one three

set --   # now $# is 0

Declare local THEN assign, on two steps. Combining them (`local var=$(cmd)`) hides the command exit code behind local's success.

⚠ Common pitfall: `local x=$(false)` always succeeds because `local` returns 0 — the inner failure is lost. Split the lines to keep `set -e` honest.

build() {
  local out
  out=$(make 2>&1) || { echo "$out" >&2; return 1; }
}

getopts works in functions, but reset `OPTIND=1` at the top so a second call re-parses from the first argument.

greet() {
  local OPTIND opt loud=0
  while getopts "l" opt; do
    case $opt in l) loud=1 ;; esac
  done
  shift $((OPTIND-1))
  (( loud )) && echo "HELLO $1" || echo "hi $1"
}

Remove a function definition. `-f` is required because a variable and a function can share the same name.

greet() { echo hi; }

unset -f greet

greet   # bash: greet: command not found

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"

Append stdout to file instead of overwriting. The file is created if it does not exist.

echo "$(date): started" >> run.log

cat extra.txt >> combined.txt

Open a file on a custom file descriptor (3 here). Then `read -u 3` reads from it; `exec 3<&-` closes it.

exec 3< data.txt

read -r first <&3

read -r second <&3

exec 3<&-

Merge stderr into stdout BEFORE the pipe, so tee captures both streams to the log and the screen.

⚠ Common pitfall: `cmd | tee log 2>&1` is wrong — only stdout reaches tee; stderr still goes straight to the terminal. Put `2>&1` before the `|`.

make 2>&1 | tee build.log

Heredoc with `<<-` strips LEADING TABS from each line (tabs only, not spaces). Lets you indent the heredoc body inside a function.

gen() {
	cat <<-EOF
		line one
		line two
	EOF
}

A bare redirect with no command truncates (empties) a file, or creates it empty if missing. The `: > file` form is the explicit idiom.

> app.log        # empty the log

: > /tmp/marker  # create/empty a marker file

Swap stdout and stderr using a temporary fd 3. After this, stdout goes where stderr went and vice versa.

# send only stdout (not stderr) down a pipe to grep:
noisy_cmd 3>&1 1>&2 2>&3 | grep -v warning

Read just the FIRST line of a file into a variable. Cheaper than `$(head -1 file)` — no subshell, no extra process.

read -r version < VERSION

echo "building $version"

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

Block until background jobs finish. `wait` waits for all; `wait -n` returns as soon as ANY one finishes (bash 4.3+).

job1 & job2 & job3 &

wait   # block until all three done

echo "all finished"

Run two commands in parallel and wait for both. A two-line "fan out then join" without external tools.

download a.url & download b.url &

wait

echo "both downloaded"

After a pipeline, ${PIPESTATUS[@]} holds the exit code of EACH command in order. Inspect a specific stage even without pipefail.

curl -fsS "$url" | gzip > out.gz

echo "curl=${PIPESTATUS[0]} gzip=${PIPESTATUS[1]}"

Fan input out to up to 4 parallel `worker` processes, one argument each. Simple bounded parallelism from a list.

cat urls.txt | xargs -P4 -n1 curl -sO

Read NUL-separated input into xargs. Pair with `find -print0` to handle filenames with spaces or newlines safely.

find . -name "*.bak" -print0 | xargs -0 rm -v

Compare the OUTPUT of two commands directly, no temp files. Process substitution feeds each side as a pseudo-file.

diff <(curl -s host1/v) <(curl -s host2/v)

diff <(echo "$a") <(echo "$b")

Reading from a pipe runs the right side in a SUBSHELL, so the variable is empty afterward. Use a here-string or process substitution instead.

⚠ Common pitfall: `echo "$x" | read y` leaves $y unset in the parent. Write `read y <<< "$x"` or `read y < <(cmd)`.

read -r first <<< "$line"

read -r n < <(wc -l < file)

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"

Safer than echo for arbitrary strings — `printf` never interprets leading `-` as an option and is portable across shells.

⚠ Common pitfall: `echo "$x"` mangles values like `-n` or `-e` (treats them as flags) and varies by shell. `printf "%s\n"` is predictable.

printf "%s\n" "-n looks like a flag"

printf "%s=%s\n" key value

Print a string in a SHELL-QUOTED form that can be safely re-used as input. Great for logging exact commands or generating scripts.

printf "run: %q %q\n" "$cmd" "$arg with space"

Strip leading whitespace using pure parameter expansion (no subshell). Mirror with a trailing-space pattern to fully trim.

s="   hi   "

lead="${s#"${s%%[![:space:]]*}"}"

echo "[$lead]"   # [hi   ]

Slurp an ENTIRE file (including trailing newlines) into one variable. `-d ""` reads until NUL, which a text file never contains.

IFS= read -rd "" content < notes.md

echo "${#content} bytes read"

Check a string is all digits (a non-negative integer) with a regex. Add a leading `-?` to allow a minus sign.

is_int() { [[ "$1" =~ ^-?[0-9]+$ ]]; }

is_int "42" && echo ok

is_int "4a" || echo "not an int"

Split command output into an array by LINES, safely keeping spaces within each line. Better than `arr=($(cmd))` which word-splits.

mapfile -t hits < <(grep -n TODO src.py)

echo "${#hits[@]} TODOs"

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)

Run a handler whenever any command fails (returns non-zero) under `set -e`. Useful for logging the failing line before exit.

set -e

trap "echo \"failed at line $LINENO\" >&2" ERR

false   # triggers the trap

Reset a trap back to the shell's default behavior for that signal. `trap - EXIT` cancels a previously installed exit handler.

trap cleanup EXIT

# ... later, when no longer needed:

trap - EXIT

A leading `+` TURNS OFF a shell option (`-` turns it on). Wrap a fragile section: `set +e; risky; set -e`.

set +e

might_fail   # do not abort on failure here

rc=$?

set -e

REPLACE the current shell process with cmd — no new process, no return. The script ends and cmd inherits its PID.

#!/usr/bin/env bash
# set up env, then hand off:
export APP_ENV=prod
exec ./server "$@"

Common signal-derived exit codes: 124 = `timeout` killed it, 130 = Ctrl-C (128+SIGINT 2), 137 = SIGKILL (128+9, e.g. OOM kill).

timeout 5 long_task

case $? in
  0) echo ok ;;
  124) echo "timed out" ;;
esac

Run cmd but kill it after the given duration, exiting 124 on timeout. Add `-k 5s` to send SIGKILL if it ignores the first signal.

timeout 30 curl -s "$url" || echo "slow endpoint"

timeout -k 5s 60s ./batch.sh

Make the ERR trap inherit into functions, command substitutions, and subshells. Without it, a `trap ... ERR` does NOT fire inside functions.

set -Eeuo pipefail

trap "echo err >&2" ERR

f() { false; }

f   # now the trap fires

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"

Assert a required variable at the top of a script. `:` is a no-op, so this line only exists to trigger the `:?` guard.

: "${DEPLOY_ENV:?set DEPLOY_ENV to dev|prod}"

: "${TOKEN:?missing TOKEN}"

Change to the script's own directory so relative paths inside it resolve regardless of where it was invoked from.

⚠ Common pitfall: Breaks when the script is reached via a symlink — `$0` is the link path. Use `${BASH_SOURCE[0]}` + `readlink -f` for symlink-proof resolution.

cd "$(dirname "$0")" || exit 1

source ./config.sh

A usage/help function built from a heredoc. Print it on `-h` or on bad arguments, then `exit`.

usage() {
  cat <<EOF
usage: $0 [-v] <src> <dst>
  -v   verbose
EOF
}

[[ "$1" == "-h" ]] && { usage; exit 0; }

Enable `**` to match files across directories recursively. After it, `**/*.js` finds every .js at any depth. Bash 4+.

shopt -s globstar

for f in src/**/*.test.ts; do echo "$f"; done

Enable extended globs: `?(x)` `*(x)` `+(x)` `@(a|b)` `!(x)`. Lets globs do alternation and negation like mini-regex.

shopt -s extglob

rm -- !(*.keep)        # delete everything except *.keep

echo @(jpg|png|gif)    # any of these

One trap covering normal exit, Ctrl-C, and kill. The most common cleanup setup for scripts that create temp resources.

workdir=$(mktemp -d)

cleanup() { rm -rf "$workdir"; }

trap cleanup EXIT INT TERM

Part of "bash strict mode": set IFS to newline+tab only, so unquoted expansions do not split on spaces. Pairs with `set -euo pipefail`.

set -euo pipefail

IFS=$'\n\t'

Run cmd only if it can grab an exclusive lock — prevents two copies of a cron job from overlapping. `-n` fails fast instead of waiting.

flock -n /tmp/job.lock ./nightly.sh || echo "already running"

Prompt for a secret without echoing keystrokes: -s silences input, -p shows the prompt. Add a trailing `echo` for the newline.

read -rsp "Password: " pw

echo

curl -u "user:$pw" "$url"

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"

Array slice: take `n` elements starting at index `s`. `"${arr[@]:1}"` drops the first element.

a=(a b c d e)

echo "${a[@]:1:2}"   # b c

echo "${a[@]: -2}"   # d e (note the space)

Rebuild an array adding elements — also the way to RE-INDEX a sparse array (close the gaps left by `unset`).

a=(x y z)

unset "a[1]"

a=("${a[@]}")   # now indices are 0,1 again

echo "${!a[@]}"   # 0 1

Join array elements into one string. Set IFS to the separator first; `[*]` glues them using IFS's first character.

parts=(2026 05 30)

IFS=-; echo "${parts[*]}"; unset IFS   # 2026-05-30

Print an array (or any variable) in a re-usable `declare` form. The fastest way to debug exactly what an array holds.

a=(one "two words" three)

declare -p a   # declare -a a=([0]="one" [1]="two words" [2]="three")

Append to an associative-array value in place. Common for accumulating counts or concatenating per-key lists.

declare -A seen

for w in a b a c a; do seen[$w]=$(( ${seen[$w]:-0} + 1 )); done

echo "${seen[a]}"   # 3

Test whether a specific associative-array KEY exists (even if its value is empty). Bash 4.3+.

declare -A cfg=([host]=a [port]="")

[[ -v cfg[port] ]] && echo "port key exists"

[[ -v cfg[tls] ]] || echo "no tls key"

Read NUL-delimited items into an array, one per element. `readarray` is a synonym for `mapfile`; `-d ""` splits on NUL.

readarray -t -d "" files < <(find . -name "*.log" -print0)

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

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

`echo -e` and `echo -n` behave differently across shells and builds. For escapes or no-newline output, use `printf` instead.

⚠ Common pitfall: On some systems `echo "-n"` literally prints `-n`. `printf "%s"` / `printf "%b"` are the predictable replacements.

printf "no newline"

printf "%b\n" "tab\there"

Assigning a command substitution always makes the assignment succeed, so `set -e` will NOT abort even if `cmd` failed.

⚠ Common pitfall: Split it: `out=$(cmd)` on its own line still hides it; check explicitly with `out=$(cmd) || exit 1` or test `$?` right after.

out=$(grep ERR log) || { echo "grep failed"; exit 1; }

`arr=($(cmd))` splits output on $IFS AND globs it — filenames with spaces or a `*` explode. Use `mapfile -t arr < <(cmd)`.

⚠ Common pitfall: A filename like `my file.txt` becomes two elements; a value `*` expands to the directory listing. `mapfile -t` splits on lines only.

mapfile -t names < <(ls)   # safe, line-by-line

Command substitution removes ALL trailing newlines. Comparing `$(cmd)` to text with a final newline will surprise you.

⚠ Common pitfall: To preserve them, append a sentinel and strip it: `out=$(cmd; printf x); out=${out%x}`.

out=$(printf "a\n\n")

echo "${#out}"   # 1 — the two newlines are gone

If `$dir` is unset/empty, `rm -rf "$dir/"` becomes `rm -rf "/"`. ALWAYS validate the variable before a destructive rm.

⚠ Common pitfall: Guard with `[[ -n "$dir" && -d "$dir" ]] || exit 1` and prefer `set -u` so an unset var errors instead of expanding to nothing.

[[ -n "${dir:-}" ]] || { echo "dir unset" >&2; exit 1; }

rm -rf -- "$dir"

`while read -r line` skips a final line that has no trailing newline, because read returns non-zero on EOF mid-line.

⚠ Common pitfall: Catch it with `while read -r line || [[ -n "$line" ]]; do ...; done` so the partial last line is still processed.

while read -r l || [[ -n "$l" ]]; do echo "$l"; done < no-trailing-newline.txt

Inside quotes, `~` stays literal: `path="~/x"` is the four characters `~/x`, not your home. Use `"$HOME/x"` instead.

⚠ Common pitfall: Tilde expansion only happens UNQUOTED and at the start of a word. `cd "~"` fails; `cd ~` or `cd "$HOME"` works.

log="$HOME/app.log"   # right

log=~/app.log         # also right (unquoted)

In old `[ ]`, an empty unquoted variable becomes a syntax error: `[ $x = y ]` with empty x is `[ = y ]`. `[[ ]]` handles it; or always quote.

⚠ Common pitfall: The classic defensive trick for `[ ]` is `[ "x$a" = "x$b" ]`. With `[[ ]]` you do not need it.

[[ "$a" == "$b" ]]   # safe even if both empty

Scripts run by cron get a bare PATH (often just /usr/bin:/bin), so tools in /usr/local/bin go missing. Use absolute paths or set PATH at the top.

⚠ Common pitfall: A script that works in your terminal can fail under cron with "command not found". Add `export PATH=/usr/local/bin:$PATH` or call binaries by full path.

#!/usr/bin/env bash
export PATH="/usr/local/bin:/usr/bin:/bin"

`source f` (or `. f`) executes f IN THE CURRENT shell — its `exit` kills your shell, its `set -e` affects you, its variables persist.

⚠ Common pitfall: A library meant to be sourced should never call bare `exit`; use `return` so the caller survives a failed load.

# in lib.sh, guard "run vs sourced":
[[ "${BASH_SOURCE[0]}" != "$0" ]] && return 0