shell-script-robust

name	shell-script-robust
description	Writes and reviews production-grade Bash/POSIX shell scripts with safety rails — set -euo pipefail, quoting, trap cleanup, shellcheck-clean, idempotency, and clear error handling. Triggers when authoring or hardening a shell/automation script, fixing a fragile script, or a shellcheck failure.
when_to_use	เขียน/แก้ bash script, automation/glue script เปราะ, ต้องการ shellcheck-clean หรือ idempotent

When to Use

• Authoring a new Bash/POSIX script (CI step, deploy glue, cron job, build wrapper).
• Hardening a fragile script: silent failures, partial runs, "works on my machine", race on temp files.
• A shellcheck run reports SC-codes and the script must pass clean.
• Making a script safe to re-run (idempotent) or adding a --dry-run path.

Do NOT use for: one-off interactive commands, or when the task is genuinely a 3-line throwaway that nobody re-runs.

Steps

1. Pick the interpreter, declare it. Bash unless POSIX sh is required (Alpine/BusyBox, /bin/sh-only targets). Shebang #!/usr/bin/env bash (or #!/bin/sh for POSIX). For Bash, set the strict header as the first executable lines:

   #!/usr/bin/env bash
   set -euo pipefail
   IFS=$'\n\t'
   

   • -e exit on error, -u error on unset var, -o pipefail so a | b fails if a fails. IFS=$'\n\t' removes space as a field separator → kills most word-splitting bugs.
   • POSIX sh has no pipefail/set -o; use set -eu only and check pipe exit manually.

2. Quote every expansion. "$var", "$@" (never $* for arg lists), "${arr[@]}", "$(cmd)". Unquoted $x undergoes word-splitting + glob expansion — the #1 source of breakage on paths with spaces. Use "${var:?missing VAR}" to fail loud on required vars, "${var:-default}" for optional.

3. Set up trap cleanup before creating any temp/lock. Create temp via mktemp, register cleanup that runs on every exit path:

   tmpdir="$(mktemp -d)"
   cleanup() { rm -rf "$tmpdir"; }
   trap cleanup EXIT INT TERM
   

   • EXIT covers normal + error exit; add INT TERM so Ctrl-C / kill also cleans. For a lock dir/file use the same pattern so a crash never leaves a stale lock.

4. Handle errors with meaningful exit codes + usage. Reserve distinct codes (64 usage, 65 data error, 69 unavailable, 1 generic — or your own scheme, documented). Add a usage() and die():

   die() { printf 'error: %s\n' "$*" >&2; exit 1; }
   usage() { printf 'usage: %s [--dry-run] <arg>\n' "$0" >&2; exit 64; }
   

   • Write diagnostics to stderr (>&2), data to stdout, so the script composes in pipelines. Check command presence up front: command -v jq >/dev/null || die "jq not found".

5. Make it idempotent + add --dry-run. Re-running must not double-apply or fail. Guard mutations: [ -d "$d" ] || mkdir -p "$d", mkdir -p over bare mkdir, ln -sfn, append only if the line is absent (grep -qF -- "$line" "$f" || printf '%s\n' "$line" >> "$f"). Thread a DRY_RUN flag and a run() wrapper:

   run() { if [ -n "${DRY_RUN:-}" ]; then printf '+ %s\n' "$*"; else "$@"; fi; }
   

6. Run shellcheck until clean; lock down portability. shellcheck -x script.sh (and -s sh if targeting POSIX). Fix at root cause — don't blanket-disable. Only add a scoped # shellcheck disable=SCXXXX with a one-line reason directly above the offending line. Bash-only features (arrays, [[ ]], ${var//}, local) are invalid in POSIX sh — if shebang is /bin/sh, shellcheck -s sh will flag them; either switch to Bash or rewrite.

7. Test with real + edge inputs. Run against: a path with spaces, an empty arg, a missing file, and a second consecutive run (idempotency). Verify exit codes (echo $?). For destructive scripts, prove --dry-run makes zero changes before running for real.

Common Errors

• set -e doesn't fire where you expect. It's suppressed inside if/while/&&/|| conditions and for the left side of a pipe (without pipefail). A failing command in cmd | grep x is invisible without -o pipefail. Also local x=$(cmd) masks cmd's exit status (the local succeeds) — split into local x; x=$(cmd).
• Unquoted $(...) in a for. for f in $(ls) breaks on spaces/newlines and globs. Use for f in *.txt (glob, with shopt -s nullglob so no-match expands to nothing) or find ... -print0 | while IFS= read -r -d '' f.
• read eats backslashes / trims whitespace. Always read -r, and IFS= read -r line to preserve leading/trailing spaces.
• cd without guard. cd "$dir" && do_thing — if the bare cd fails under set -e you may still be in the wrong dir. Guard it: cd "$dir" || die "cd failed".
• rm -rf "$base/$sub" with unset vars. If base is empty, this can become rm -rf /.... set -u + "${base:?}" prevents the empty-expansion footgun. Never rm -rf a variable you didn't validate.
• trap registered after the temp is made. If creation succeeds but the next line fails, cleanup never registered → leak. Register the trap immediately after mktemp.
• echo with flags/backslashes is non-portable. Prefer printf '%s\n' "$x".
• Shebang lies. #!/bin/sh + bash arrays → silently broken on dash. Match shebang to the features you actually use.

Verify

• shellcheck -x script.sh (add -s sh for POSIX targets) → zero warnings, or only scoped disables each with a reason comment.
• bash -n script.sh parses clean (syntax check, no execution).
• Run the strict header check: confirm set -euo pipefail (Bash) is present and the script still completes on valid input.
• Idempotency: run twice in a row → second run is a no-op or succeeds identically; no stale temp/lock left behind (ls the temp dir after — gone).
• Edge inputs pass: path with a space, missing required arg exits non-zero with usage on stderr, --dry-run produces zero side effects.
• command -v preflight catches missing dependencies before any mutation runs.