shell-scripting

Write safe, portable shell

Shell is where quiet failures live: an unset variable expands to nothing, a failed command inside a condition is ignored, a filename with a space becomes two arguments, and two runs share one temp file. For the builder and the reviewer of a shell diff; the repo's existing scripts win over it.

Procedure

1. Discover the repo's conventions first. Call search_lore and read the existing scripts: the shebang (#!/usr/bin/env bash vs POSIX #!/bin/sh), the strict-mode line, sourced helper libraries, logging helpers, .shellcheckrc, .editorconfig (shfmt reads indentation from it), the test harness (bats, or the repo's test/*.test.sh pattern) and which OSes CI runs. macOS ships bash 3.2: no associative arrays, mapfile, ${var,,}, and "${arr[@]}" on an empty array fails under set -u before bash 4.4. Match the repo; do not introduce a second style.
2. Decide it should be shell at all. Google's guide: past ~100 lines, or with non-trivial data structures, write it in the repo's main language instead.
3. Write the change with the idioms below, then walk the failure section for every pipeline, condition, temp file and background job.
4. Test each acceptance criterion's own behaviour. Run the script against a fixture directory and assert exit code, output and side effects, including one failure case (missing input, failing dependency) that must exit non-zero. If the script can run concurrently (CI jobs, cron, hooks), start two copies at once and assert neither corrupts the other's output.
5. Verify, then stop. Done when: bash -n passes, shellcheck -x is clean at the repo's severity (each disable has a code and reason), shfmt shows no diff if the repo uses it, the tests pass, and every AC has a test. Record the output with the record-evidence skill; the runner submits the work.

Commands

• Syntax: bash -n script.sh (sh -n for POSIX scripts).
• Lint: shellcheck -x script.sh (add -S warning or the repo's severity; -s sh for POSIX).
• Format: shfmt -d . when the repo uses shfmt.
• Tests: bats test/ or the repo's bash runner/test/x.test.sh pattern.
• In your own Bash tool calls (not the script), the safety hook blocks $(…) or backticks combined with a read tool (grep, cat, sort, head, cp…) and any rm -rf: put such logic inside the script or its test file and run that.