Bash Scripting skill for Claude Code

Done well means: shellcheck reports nothing, the script stops at the first unexpected failure with a message naming what failed, every variable expansion is quoted, temp files are cleaned up on any exit, rerunning the script is safe, and --help explains usage.

Ground rules

• Decide the interpreter first. Bash features (arrays, [[ ]], local, pipefail) require #!/usr/bin/env bash. #!/bin/sh means POSIX only (dash on Debian/Ubuntu).
• Quote every expansion: "$var", "${arr[@]}", "$(cmd)". Unquoted is the exception and needs a reason.
• Scripts over ~150 lines, or that parse JSON, do arithmetic on floats, or need data structures beyond flat arrays, belong in Python (stdlib) instead.
• Destructive operations (rm -rf, overwriting files, pushing, deploying) need an explicit confirmation or --force flag, and guards against empty variables.
• macOS ships bash 3.2 and BSD userland. If the script must run there, avoid bash 4+ features or require Homebrew bash explicitly.

Template

#!/usr/bin/env bash
# Purpose: one line describing what this does.
# Usage: ./sync-assets.sh [-n] [-v] <source-dir> <bucket>
set -Eeuo pipefail
shopt -s inherit_errexit 2>/dev/null || true   # bash 4.4+: $(...) inherits -e

readonly SCRIPT_NAME="${0##*/}"
# Need the script dir? Assign, then mark readonly on its own line (SC2155):
# SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"; readonly SCRIPT_DIR

log()  { printf '%s [%s] %s\n' "$(date -u +%H:%M:%S)" "$SCRIPT_NAME" "$*" >&2; }
die()  { log "ERROR: $*"; exit 1; }
usage() {
  cat <<EOF
Usage: $SCRIPT_NAME [-n] [-v] <source-dir> <bucket>
  -n  dry run: print actions without executing
  -v  verbose (set -x)
  -h  show this help
EOF
}

on_error() { log "failed at line $1: $2 (exit $3)"; }
trap 'on_error "$LINENO" "$BASH_COMMAND" "$?"' ERR

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

dry_run=0
while getopts ":nvh" opt; do
  case "$opt" in
    n) dry_run=1 ;;
    v) set -x ;;
    h) usage; exit 0 ;;
    :) die "option -$OPTARG requires an argument" ;;
    *) usage >&2; exit 2 ;;
  esac
done
shift $((OPTIND - 1))
[[ $# -eq 2 ]] || { usage >&2; exit 2; }

src="$1"; bucket="$2"
[[ -d "$src" ]] || die "source dir not found: $src"
command -v aws >/dev/null || die "aws CLI not installed"

run() { if (( dry_run )); then log "DRY: $*"; else "$@"; fi; }

main() {
  log "syncing $src -> s3://$bucket"
  run aws s3 sync "$src" "s3://$bucket" --only-show-errors
  log "done"
}
main "$@"

Exit codes: 0 success, 1 runtime failure, 2 usage error. Logs go to stderr so stdout stays clean for data.

Strict mode: what it does and where it lies

Setting	Effect	Trap
set -e	Exit on unhandled non-zero status	Ignored inside if, while, &&/`
set -u	Unset variables are errors	Use "${VAR:-}" for optional env vars; "${arr[@]}" on empty arrays errors in bash < 4.4
set -o pipefail	Pipeline fails if any stage fails	grep exits 1 on no match; head closing early can make the writer fail with SIGPIPE
set -E	ERR trap inherited by functions and subshells	Needed for the ERR trap to fire inside functions

# set -e does not catch this: local masks the exit status
local out=$(failing_cmd)            # wrong
local out; out=$(failing_cmd)       # right

# Expected non-zero: say so explicitly
if ! grep -q "pattern" file; then log "no match"; fi
count=$(grep -c "x" file || true)

Quoting and arrays

files=( "$dir"/*.log )                       # glob into an array; quote the directory part
[[ -e "${files[0]}" ]] || files=()           # no matches: glob stays literal unless nullglob
for f in "${files[@]}"; do gzip -- "$f"; done

args=( --region "$region" --profile "$profile" )
[[ -n "${DRY_RUN:-}" ]] && args+=( --dryrun )
aws s3 cp "${args[@]}" "$src" "$dst"         # build commands as arrays, never as strings

while IFS= read -r line; do                  # read lines safely (keeps spaces/backslashes)
  printf '%s\n' "$line"
done < "$input"

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

• printf '%s\n' "$x" over echo "$x" (echo mangles -n, -e, backslashes).
• -- before filenames that may start with -.
• [[ ]] in bash: no word splitting inside, supports =~ and &&. [ ] in POSIX sh.
• $(...) not backticks. $(( )) for integer math.
• Never parse ls. Use globs or find -print0.

Safe destructive operations

: "${TARGET_DIR:?TARGET_DIR must be set}"       # abort if empty or unset
[[ "$TARGET_DIR" != "/" && "$TARGET_DIR" == /srv/app/* ]] || die "refusing to delete $TARGET_DIR"
read -r -p "Delete $TARGET_DIR? [y/N] " reply
[[ "$reply" == [yY] ]] || die "aborted"
rm -rf -- "$TARGET_DIR"

• rm -rf "$DIR/"* with an unset DIR deletes from /. set -u plus :? guards stop it.
• Write files atomically: write to "$tmpdir/out" then mv into place (same filesystem).
• Idempotency: mkdir -p, ln -sfn, grep -qxF "$line" file || echo "$line" >> file, check-before-create for cloud resources.
• Lock against concurrent runs with flock on Linux (exec 9>/var/lock/x; flock -n 9 || die "running"); macOS has no flock by default — use mkdir "$lockdir" as an atomic lock.

Portability

Need	Portable approach
In-place sed	sed -i.bak 's/a/b/' f && rm f.bak (works on GNU and BSD)
Script directory	cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd (no readlink -f on old macOS)
Date math	Avoid; GNU date -d and BSD date -v differ. Use Python if needed
Lowercase	tr '[:upper:]' '[:lower:]' (${var,,} is bash 4+)
Associative arrays	bash 4+ only; not on stock macOS
mapfile/readarray	bash 4+ only; use a while read loop
grep -P	GNU only; use grep -E

For the full GNU vs. BSD vs. POSIX difference list, read references/portability.md when the script must run on macOS, Alpine (busybox), or /bin/sh.

CI and container scripts

• Print the commands that matter (set -x behind a -v flag or DEBUG=1), never secrets. Turn tracing off around secret handling: { set +x; } 2>/dev/null.
• Pass secrets through env vars or files, not arguments (visible in ps).
• curl -fsSL --retry 3 so HTTP errors fail the script; verify downloaded checksums (sha256sum -c / shasum -a 256 -c).
• exec "$@" at the end of container entrypoints so signals reach the main process.

Workflow

- [ ] 1. Choose bash vs sh vs Python (size, data structures, portability target)
- [ ] 2. Start from the template: strict mode, traps, usage, arg parsing
- [ ] 3. Validate inputs and required tools up front
- [ ] 4. Guard destructive steps; add a dry-run mode
- [ ] 5. shellcheck until clean; fix, do not disable, unless a directive has a comment
- [ ] 6. Test the failure paths: missing args, missing tool, failing command mid-run
- [ ] 7. Run twice to prove idempotency

Verification

shellcheck -x -S style script.sh           # -x follows sourced files
bash -n script.sh                          # syntax check
shfmt -d -i 2 script.sh                    # formatting, if shfmt is available
./script.sh -h; ./script.sh; echo "exit=$?"   # usage and missing-arg path exits 2

Disable a shellcheck rule only inline with a reason: # shellcheck disable=SC2086 # intentional word splitting of $FLAGS.