shell-writer

name	shell-writer
description	Shell scripting correctness and structure — dialect detection, strict-mode headers, quoting discipline, clean script layout, and the silent failure modes of pipes, subshells, and word splitting. Load before writing or editing shell scripts.
activation	{"extensions":["sh","bash","zsh"]}

Shell Writer

How to write shell that fails loudly instead of succeeding wrongly: know which dialect the file is, quote every expansion, and assume any command can fail.

Dialect first

• The shebang decides the language. #!/bin/sh means POSIX only: no arrays, no [[ ]], no local -n, no ${var,,}. #!/usr/bin/env bash unlocks bashisms. Match the file's existing shebang — don't add bash features to an sh script.

• New bash scripts start with strict mode:

  #!/usr/bin/env bash
  set -euo pipefail
  

  Know its limits: -e is suppressed inside if/while conditions and on the left of ||/&&, and local x=$(cmd) masks cmd's exit code — declare and assign on separate lines when the status matters.

Quote everything

• "$var", "$@" (never bare $*), "$(cmd)" — unquoted expansions word-split and glob, which is the single most common script bug. Filenames with spaces are the test case.
• Build command arguments in a bash array (args=(-x "$file"); cmd "${args[@]}"), not by concatenating a string. Avoid eval entirely.
• Prefer [[ ]] over [ ] in bash (no word-splitting inside); prefer $( ) over backticks.

Everything can fail

• cd can fail — cd "$dir" || exit 1 (or rely on set -e, knowing its exceptions). Same for mkdir, rm, and anything touching the filesystem.
• Check that non-standard tools exist before calling them: command -v jq >/dev/null || { echo "jq required" >&2; exit 1; }.
• A pipe runs each side in a subshell: cmd | while read -r line; do count=$((count+1)); done loses count. Feed loops with redirection (while read -r … done < file) or process substitution (< <(cmd)) when you need to keep variable updates.
• Errors go to stderr (echo "…" >&2); exit non-zero on failure so callers can react.

Files and cleanup

• tmp=$(mktemp) for temp files, paired with trap 'rm -f "$tmp"' EXIT so cleanup survives early exits.
• Handle arbitrary filenames end-to-end: find … -print0 | xargs -0 …, read -r, and quoted expansions throughout.

Clean script structure

• Anything beyond a few lines gets functions: lowercase_underscore names, local for every function variable, constants as readonly NAME=… at the top, environment/exported variables in UPPER_CASE.
• Larger scripts follow the main pattern — logic in functions, a main() that orchestrates, and main "$@" as the last line, so nothing executes during a partial source or review.
• A script with flags gets a usage() printed on -h/bad args; parse with while getopts (bash) rather than ad-hoc $1 juggling.
• Prefer shell built-ins over spawning processes for simple work: parameter expansion (${file%.txt}, ${var:-default}) instead of sed/awk round-trips; $(( )) for arithmetic.
• Long-running or destructive scripts log progress to stderr and aim for idempotence — re-running after a partial failure should be safe.

Verify

• bash -n script.sh for a syntax gate; then execute the real flow — dry reads prove nothing in shell.
• Run shellcheck when it's available and fix what it flags; it knows every pitfall on this page and more.

Know when to stop

A script that needs data structures, error recovery, or is growing past ~100 lines of logic has outgrown shell — moving it to a real language is the correct fix, not more bash.