Bash Scripting skill for Codex

A good script stops at the first unexpected failure, survives filenames with spaces, newlines and leading dashes, cleans up after itself on every exit path, and passes shellcheck with no unexplained suppressions. If the logic needs data structures, JSON parsing or more than ~200 lines, write it in Python instead and say so.

Before writing

1. Read AGENTS.md and any existing scripts (rg --files -g '*.sh') to match conventions: indentation, logging helpers, where scripts live, how CI runs them.
2. Decide the target shell. Check where it runs: CI images and Linux servers have Bash 5.x; stock macOS ships Bash 3.2 at /bin/bash (no mapfile, no associative arrays, no ${var,,}). Alpine and distroless images may have no Bash at all, only sh.
3. If the script must run under /bin/sh, write POSIX sh and drop every Bash-only feature in the table below. Do not put #!/bin/sh on a script that uses [[.

Need	Bash 4+	Bash 3.2 / POSIX fallback
Read lines into array	mapfile -t lines < file	while IFS= read -r l; do lines+=("$l"); done < file (3.2)
Lowercase	${v,,}	tr '[:upper:]' '[:lower:]'
Map / dict	declare -A m	two parallel arrays, or switch language
Test	[[ $a == b* ]]	case $a in b*) ...;; esac (POSIX)

Script skeleton

Start every new script from this shape:

#!/usr/bin/env bash
# Rotates application logs older than N days into an archive directory.
set -Eeuo pipefail
shopt -s inherit_errexit 2>/dev/null || true   # Bash 4.4+: $(...) inherits -e

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

log()  { printf '%s %s\n' "$(date -u +%FT%TZ)" "$*" >&2; }
die()  { log "ERROR: $*"; exit 1; }

usage() {
  cat <<'EOF'
Usage: rotate-logs.sh [-n DAYS] [--dry-run] LOG_DIR
  -n DAYS     age threshold in days (default 14)
  --dry-run   print what would move, change nothing
EOF
}

tmpdir=""
cleanup() { if [[ -n $tmpdir ]]; then rm -rf -- "${tmpdir:?}"; fi; }
trap cleanup EXIT
trap 'log "failed at line $LINENO: $BASH_COMMAND"' ERR

main() {
  local days=14 dry_run=0
  while (($#)); do
    case $1 in
      -n) days=${2:?-n needs a value}; shift 2 ;;
      --dry-run) dry_run=1; shift ;;
      -h|--help) usage; exit 0 ;;
      --) shift; break ;;
      -*) die "unknown option: $1" ;;
      *) break ;;
    esac
  done
  (($# == 1)) || { usage >&2; exit 2; }
  local dir=$1
  [[ -d $dir ]] || die "not a directory: $dir"

  tmpdir=$(mktemp -d)
  # ... work ...
}

main "$@"

Why each piece matters:

• -e exits on an unchecked failure, -u on unset variables, pipefail makes cmd | grep x fail when cmd fails, -E lets the ERR trap fire inside functions.
• trap cleanup EXIT runs on success, failure and Ctrl-C; temp files never leak.
• Wrapping in main "$@" stops a half-downloaded script (curl | bash) from running.
• Logs go to stderr so stdout stays machine-readable.

Quoting and expansion rules

• Quote every expansion: "$var", "$(cmd)", "${arr[@]}". The exceptions are the right side of [[ ]] assignments and case subjects, and even there quoting is harmless.
• Use arrays for argument lists, never strings:

args=(--archive --compress --exclude '*.tmp')
[[ $verbose == 1 ]] && args+=(--verbose)
rsync "${args[@]}" -- "$src/" "$dest/"

• Put -- before user-controlled paths so -rf as a filename is not an option.
• Guard destructive paths: rm -rf -- "${dir:?}/cache" aborts if dir is empty instead of deleting /cache.
• printf '%s\n' "$x", not echo "$x": echo mangles -n, -e and backslashes.
• Read lines with while IFS= read -r line; do ...; done < "$file"; -r keeps backslashes, IFS= keeps leading spaces.
• Iterate files with globs or NUL delimiters, never for f in $(ls) or $(find ...):

shopt -s nullglob
for f in "$dir"/*.log; do gzip -- "$f"; done

find "$dir" -type f -name '*.log' -mtime +"$days" -print0 |
  while IFS= read -r -d '' f; do mv -- "$f" "$archive/"; done

Where set -e does not protect you

Situation	What happens	Fix
local out=$(cmd)	exit status of local (0) masks cmd	local out; out=$(cmd)
if f; then / f || true / f && g	-e is disabled inside f entirely	check statuses explicitly inside functions used in conditions
$(cmd) in Bash < 4.4 without inherit_errexit	failure inside substitution ignored	shopt -s inherit_errexit, or assign then test
cmd | while read ...	loop runs in a subshell; variables set inside vanish	while ...; done < <(cmd)
(( count++ )) when count is 0	arithmetic result 0 returns status 1, script exits	count=$((count + 1))
grep with no match	status 1 kills the script	grep ... || true, or test with if grep -q

Check external command status deliberately when the failure is expected:

if ! out=$(curl -fsS --max-time 10 "$url"); then
  die "health check failed for $url"
fi

Common operations done right

command -v jq >/dev/null || die "jq is required"          # dependency check
: "${API_TOKEN:?API_TOKEN must be set}"                    # required env var
lock=/tmp/myjob.lock; exec 9>"$lock"; flock -n 9 || die "already running"  # Linux flock
retry() { local n=0; until "$@"; do ((++n >= 5)) && return 1; sleep $((2 ** n)); done; }
retry curl -fsS -o "$tmpdir/pkg.tgz" "$url"

• Use mktemp / mktemp -d; never fixed names like /tmp/out.txt.
• Write files atomically: write to "$target.tmp.$$", then mv -f into place.
• date, sed -i, readlink -f, stat and grep -P differ between GNU and BSD (macOS). Use sed -i.bak (works on both) or avoid in-place edits; check uname only when unavoidable.
• Heredocs: quote the delimiter (<<'EOF') unless you want expansion inside.

Destructive and outward-facing steps

Scripts that delete data, deploy, push, or call production APIs must:

• default to a dry run or require an explicit --yes flag;
• print exactly what will change before changing it;
• never be executed by you against real environments without the user confirming the target and the command in chat first.

confirm() {
  [[ ${ASSUME_YES:-0} == 1 ]] && return 0
  read -r -p "$1 [y/N] " reply </dev/tty
  [[ $reply == [yY] ]]
}
confirm "Delete ${#stale[@]} branches on origin?" || die "aborted"

Verification loop

• bash -n script.sh parses.
• shellcheck -x script.sh is clean. Each # shellcheck disable=SCxxxx has a one-line reason on the line above. ShellCheck may need installing (brew install shellcheck, apt-get install shellcheck); that needs network and approval.
• shfmt -i 2 -ci -d . shows no diff (or match the indent AGENTS.md specifies).
• If ShellCheck is unavailable offline, run the bundled hazard scan: python3 scripts/bash_hazards.py path/to/script.sh (stdlib only; exits 1 on findings). It is a fallback, not a substitute.
• Run the script with a filename containing a space, a leading dash and a newline, with an empty input dir, and with a missing dependency. Each must behave.
• For scripts with logic, add bats-core tests:

# test/rotate.bats
setup() { TMP=$(mktemp -d); touch "$TMP/a b.log"; }
teardown() { rm -rf -- "$TMP"; }

@test "dry run moves nothing" {
  run ./rotate-logs.sh --dry-run -n 0 "$TMP"
  [ "$status" -eq 0 ]
  [ -e "$TMP/a b.log" ]
}

@test "rejects missing directory" {
  run ./rotate-logs.sh /nonexistent
  [ "$status" -ne 0 ]
}

Run with bats test/. On failure, rerun with bash -x script.sh to trace, fix the cause, and add a test for the case.

Gotchas

• cd somewhere without || exit (or -e) runs the rest of the script in the wrong directory; with rm that is how home directories get deleted.
• [ $x = y ] breaks when x is empty or has spaces; [[ $x == y ]] does not.
• ~ does not expand inside quotes; use "$HOME/...".
• set -u plus an empty array: "${arr[@]}" errors on Bash < 4.4. Use ${arr[@]+"${arr[@]}"} when targeting macOS Bash 3.2.
• CRLF line endings produce $'\r': command not found; check with file script.sh.
• sourced files inherit strict mode; scripts that are meant to be sourced into an interactive shell must not set -e globally or exit.
• Cron runs with a minimal PATH and no profile; set PATH explicitly at the top.

Output

When delivering a script, report: target shell and minimum version, what it changes, the dry-run command, the ShellCheck result, and which edge cases you exercised.