linux-bash-scripting

Linux Bash Scripting

Produce bash scripts that pass shellcheck --enable=all and shfmt -d with zero warnings.

Target: GNU Bash 4.4+ on Linux. No macOS/BSD workarounds, no Windows paths, no POSIX-only restrictions.

Script Foundation

#!/usr/bin/env bash
set -Eeuo pipefail
shopt -s inherit_errexit

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

trap 'printf "Error at %s:%d\n" "${BASH_SOURCE[0]}" "$LINENO" >&2' ERR
trap 'rm -rf -- "${_tmpdir:-}"' EXIT

• -E propagates ERR traps into functions
• inherit_errexit propagates errexit into $() command substitutions
• Resolve the script's own data files against SCRIPT_DIR, never the caller's cwd or git rev-parse --show-toplevel. A shared linter invoked from another project's git hook, a cron job, or a wrapper runs with someone else's cwd, so a caller-relative rules path resolves to a file that does not exist: the rule set loads empty, zero violations are found, exit 0. It is a silent no-op, not an error, and running it from inside its own repo passes for the wrong reason. Exercise it once from a scratch directory that is not the script's own tree
• Always create temp dirs under the EXIT trap: _tmpdir=$(mktemp -d)
• Wrap body in main() { ... } with source guard: [[ "${BASH_SOURCE[0]}" == "$0" ]] && main "$@" -- enables sourcing for testing

Core Rules

• Quote every expansion: "$var", "$(cmd)", "${array[@]}"
• local for function variables, local -r for function constants, readonly for script constants
• printf '%s\n' over echo -- predictable behavior, no flag interpretation
• [[ ]] for conditionals; (( )) for arithmetic; $() over backticks
• End options with --: rm -rf -- "$path", grep -- "$pattern" "$file"
• Require env vars: : "${VAR:?must be set}"
• Never eval user input; build commands as arrays: cmd=("grep" "--" "$pat" "$f"); "${cmd[@]}"
• Keep untrusted/derived bytes off the command line: never build a heredoc body or an sh -c string from external data. An unquoted <<EOF command-substitutes $(...)/backticks in the content, and even a quoted <<'EOF' breaks if a content line equals the delimiter (the heredoc ends early and the rest runs as shell). Write the data to a file with a non-shell writer and have the consumer read the file
• Allowlisting a command? Match the whole command against an anchored pattern (^…$), never inspect individual arguments — shell operators (;, &&, |, #, newline) smuggle a second command past a per-argument check (rm -rf node_modules; rm -rf /). Unrecognized syntax must fail closed to deny/ask
• Validate a numeric before it reaches (( )) or $(( )) when it came from a file, env var, or command output rather than a literal. Two distinct failures: (1) command execution -- arithmetic evaluates an array subscript, so a value of a[$(cmd)] runs cmd (a bare $(cmd) is only a syntax error, so testing that form will wrongly suggest the trap isn't real); (2) octal abort -- a leading zero makes 08 base-8 and $(( v + 1 )) dies with value too great for base, taking the script down under set -e. Gate on [[ "$v" =~ ^-?[0-9]+$ ]] first, then force base 10 with $(( 10#$v )) for zero-padded input
• Separate local from assignment to preserve exit codes: local val; val=$(cmd)
• Debug tracing: PS4='+${BASH_SOURCE[0]}:${LINENO}: ' with bash -x -- shows file:line per command
• Named exit codes: readonly EX_USAGE=64 EX_CONFIG=78 -- no magic numbers in exit
• Pipeline diagnostics: "${PIPESTATUS[@]}" shows exit code of each pipe stage, not just last failure
• Branch on a probe's exact exit status, not on nonzero-versus-zero. A tool that exits 2 for "ran, found nothing" and 128 for "could not run" collapses into a single negative under if ! cmd, and stderr is often empty for both. Treating every silent nonzero as "absent" converts a network, permission, or spawn failure into a confident false diagnosis
• A || B is a fallback only when A fails on the case B exists for. When A succeeds while doing the wrong thing -- resolving a different tool, default, or directory -- B is dead code and the wrong behavior is silent. Same trap in ${VAR:-default} on a path two processes must agree on: whoever lacks VAR gets a different location, the two silently stop sharing state, and neither errors. Pick one resolution and fail loudly when it is unavailable