contexture bash.instructions.md

bash rules

Auto-loaded by Copilot when editing files matching **/*.sh. Generated from architectural-rules/bash/ — do not hand-edit.

Bash quoting

Quote every variable expansion: "$var", "${arr[@]}". Unquoted expansions word-split and glob-expand — the source of nearly every "works until a path has a space" bug. Use "$@" (not $*, not unquoted $@) to forward arguments — it preserves each argument as a separate quoted word. $* joins them into one string. Use [[ ... ]] over [ ... ] for tests — no word-splitting inside, supports &&/||/=~, and doesn't break on empty variables. Use $(command) over backticks for command substitution — it nests cleanly and is readable. ⚠ Never use PowerShell here-string syntax (@'...'@) inside a bash command. Bash parses @'text'@ as a literal @, then a single-quoted string, then a trailing @ — so a leading @ leaks silently into the output. A leading @ then silently prefixes the commit subject. For multi-line commit messages in bash use $'line1\nline2', a real here-doc (-F - with <<'EOF'), or -F <file>. Read back the subject (git log -1 --format=%s) after committing to catch it.

Why: unquoted expansion is the single most common shell bug class — it passes every test with simple inputs and breaks the moment a filename has a space or a variable is empty. Source: Google Shell Style Guide, ShellCheck (SC2086). The here-string landmine is sharper on Windows where PowerShell is the other shell in muscle memory — the syntaxes look interchangeable and are not.

Bash safety

Start scripts with set -euo pipefail: -e exit on error, -u error on unset variable, -o pipefail so a failure anywhere in a pipe fails the pipe. Without these, errors are silently ignored and the script charges on. Set IFS=$'\n\t' when word-splitting matters — the default IFS splits on spaces too and mangles paths/filenames with spaces. Clean up with trap 'cleanup' EXIT — temp files and locks get removed even on early exit or error. Don't rely on reaching a cleanup line at the bottom. Verify required commands exist up front (command -v jq >/dev/null || { echo "jq required" >&2; exit 1; }) instead of failing cryptically halfway through. Terminate only the process you started, by the PID you captured (kill "$pid"). Never pkill / kill / taskkill by name or pattern — name-matching also kills unrelated processes (e.g. pkill godot to stop a headless run also takes down the user's open editor).