Bash

User preferences live in ~/Clawic/data/bash/config.yaml (see Configuration); nothing else is stored on the user's machine. If you have data at an old location (~/bash/ or ~/clawic/bash/), move it to ~/Clawic/data/bash/.

When To Use

• Writing or reviewing any Bash beyond a one-liner: CI steps, deploy scripts, cron tasks, entrypoints, glue code
• Debugging scripts that break on spaces in filenames, fail silently, hang, or exit with the wrong code
• Hardening an existing script: strict mode, cleanup traps, argument parsing, re-runnability, portability
• Porting a script between macOS and Linux, or down to POSIX sh
• Deciding whether the task belongs in Bash at all (Core Rule 9)
• Not for POSIX-sh-only targets (dash, busybox, alpine /bin/sh) — most patterns here are bashisms; portability.md covers the downgrade

Quick Reference

Each file above is one sub-job and is self-contained: read SKILL.md by default, open exactly one guide when the situation matches.

Core Rules

1. Open every script with #!/usr/bin/env bash and set -euo pipefail, then learn the -e holes (errors.md) instead of dropping strict mode — the holes are enumerable; silent failures are not.
2. Quote every expansion: "$var", "$(cmd)", "${arr[@]}". An unquoted expansion is a deliberate act that carries a comment saying why. Word splitting plus globbing is Bash's #1 bug class (shellcheck SC2086).
3. Build commands as arrays, never as strings. opts="--exclude '*.log'"; rsync $opts src dst passes the quotes as literal characters; opts=(--exclude '*.log'); rsync "${opts[@]}" src dst passes --exclude and *.log as two clean arguments. Conditional flags append: [[ $dry == 1 ]] && opts+=(--dry-run).
4. Run shellcheck before shipping, blocking at lint_gate severity. Suppress only with the code and a reason on the same line: # shellcheck disable=SC2086 -- flags must split.
5. Know your floor: macOS /bin/bash is 3.2 forever (GPLv3 freeze). If the script uses any bash >=4.0 feature (Version Floors), state the floor in a header comment and enforce it: ((BASH_VERSINFO[0] >= 4)) || { echo "needs bash 4+" >&2; exit 1; }.
6. Never parse ls. Iterate with globs or find -print0: filenames may contain newlines, so NUL is the only delimiter a filename cannot contain.
7. Test the failure path before delivering: swap one command for false, confirm the script stops, the trap fires, and the exit code is nonzero. A cleanup you never saw run is a cleanup you do not have.
8. Untrusted input never reaches eval, arithmetic, or array subscripts: (( $userinput )) executes commands via arr[$(cmd)] subscripts. Gate with a regex first: [[ $n =~ ^[0-9]+$ ]] || die "not a number: $n".
9. Past rewrite_threshold lines (default 100, the Google Shell Style Guide cutoff) or once you need nested data structures, rewrite in Python or similar. Bash orchestrates processes; it does not model data.

Script Skeleton

#!/usr/bin/env bash
# Requires bash >= 4.4 (inherit_errexit). Run: script.sh [-n] 
set -euo pipefail
shopt -s inherit_errexit 2>/dev/null || true   # bash >=4.4: $(cmd) failures propagate

die() { printf '%s\n' "$*" >&2; exit 1; }

tmp=$(mktemp) || die "mktemp failed"
trap 'rm -f "$tmp"' EXIT   # single-quoted: expands when it FIRES, not now
                           # fires on error and normal exit; kill -9 bypasses all traps

Quoting

• "$var", "$(cmd)", "${arr[@]}" — always. $(cmd) strips ALL trailing newlines, not just one.
• Single quotes are literal; $'...' interprets escapes: $'\t', $'\r', $'\0'.
• Filenames from variables get -- or ./: rm -- "$f" survives a file named -rf.
• echo "$var" breaks when var is -n, -e, or has backslashes — printf '%s\n' "$var" never does.
• Arguments to ssh/su -c/bash -c are re-parsed by the receiving shell — build them with printf '%q ' (quoting.md).
• ${arr[*]} joins with the first char of IFS into one word; "${arr[@]}" preserves elements. Joining is the only reason to write [*].

Version Floors

macOS /bin/bash stays at 3.2. #!/usr/bin/env bash finds a Homebrew bash on PATH; #!/bin/bash never will. Check at runtime with BASH_VERSINFO, not by parsing bash --version.

Exit Codes

Formula: a code above 128 means killed by signal code − 128. Codes are mod 256 — exit 256 reports 0, exit -1 reports 255.

Subshells and State

• Every pipe segment runs in a subshell: cmd | while read -r x; do ((n++)); done loses n. Fix: done < <(cmd), or shopt -s lastpipe (bash >=4.2, scripts only).
• ( ) is a subshell, { ...; } is the current shell — exit inside ( ) or $( ) exits only that subshell.
• Background jobs: cmd & pid=$! then wait "$pid" — wait returns the job's exit code, your only way to check it.
• cd inside ( ) to visit a directory without having to cd back.

Robust Iteration

• Globs: shopt -s nullglob first — otherwise for f in *.txt in an empty dir runs once with the literal string *.txt.
• Hostile filenames or recursion: while IFS= read -r -d '' f; do ...; done < <(find . -name '*.log' -print0).
• Lines of a file: while IFS= read -r line; do ...; done < file — IFS= keeps leading whitespace, -r keeps backslashes. A final line without a trailing newline is still skipped: append || [[ -n $line ]] to the read.
• Any command inside the loop that reads stdin (ssh, ffmpeg, mysql) eats the rest of the input and the loop ends after one pass — pass ssh -n or redirect < /dev/null.
• Split a string: IFS=, read -ra fields <<< "$csv". Join: (IFS=,; echo "${arr[*]}") — the subshell keeps the IFS change local.

Output Gates

Before delivering any script, check:

• Every expansion quoted, or the unquoted one carries a comment saying why
• Commands with variable flags built as arrays, not concatenated strings
• shellcheck clean at lint_gate, or each disable names its SC code and reason
• Failure path exercised: injected false, watched the trap fire and the exit code go nonzero
• Bash floor stated in a header comment and matching bash_floor if any bash >=4.0 feature is used
• No eval; no unvalidated input inside (( )) or array subscripts
• Re-runnable: a run that dies halfway leaves nothing half-written — temp file plus mv, mkdir -p, rm -f
• Destructive steps gated per destructive_confirm; no secret can appear in set -x output or ps

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/bash/config.yaml. Never interview the user — record a preference the moment it is stated.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Tooling: shellcheck/shfmt/bats availability, GNU coreutils on macOS (gsed, gdate), jq vs python for JSON — affects testing.md gates and every parsing example
• Conventions: function and variable naming, usage/help layout, log line format, script header content — affects functions.md and arguments.md output
• Platform: bash floor and OS mix, POSIX-sh-only targets, alpine images where /bin/sh is ash and bash may be absent — affects portability.md guidance
• Safety posture: whether scripts may sudo, dry-run first, banned constructs (eval, curl | sh, rm -rf on a variable) — affects security.md and destructive workflows
• Runtime home: where the script actually runs unattended — cron, systemd timer, launchd, CI runner, container entrypoint — affects cron.md and ci.md advice
• Output: verbosity, color only when the output is a TTY, timestamps, quiet or machine-readable logging — affects interactive.md and logging helpers

Traps

Where Experts Disagree

• set -e: the strict-mode school makes it mandatory; the Google Shell Style Guide school argues its exceptions (conditions, ||, command substitution) make it false comfort and prefers explicit || die. Boundary: short glue scripts → strict mode; sourced libraries and functions whose return codes callers inspect → explicit handling. Never mix philosophies in one file.
• Bash vs POSIX sh: write sh only when the target set actually contains dash/busybox/alpine. "Portable by default" costs arrays, [[ ]], and set -o pipefail for hosts you may never meet.
• Returning values from functions: print to stdout and capture (composable, costs a fork per call) vs write through a nameref or a documented global (no fork, couples caller and callee). Boundary: hot loops and large payloads → nameref (bash >=4.3); everything else → stdout.
• Long options: GNU getopt(1) parses them but does not exist usably on macOS (BSD getopt has no long options); a hand-rolled while/case loop is portable and you own the error messages. Boundary: Linux-only tooling → getopt; anything shipped to laptops → hand-rolled (arguments.md).

Related Skills

More Clawic skills, get them at https://clawic.com/skills/bash (install if the user confirms):

• linux — when the bug is the system, not the script: permissions, cron daemon config, systemd units, OOM
• regex — when the =~ pattern itself is the hard part
• github-actions — when the script lives in CI and the failure is workflow wiring, not shell
• cli-design — when the question is the tool's interface: subcommand layout, flag naming, help text contract

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/bash.