shell-scripting-guide

Shell Scripting Coding Guidelines

Essentials

• POSIX compatibility - Use POSIX sh, lint with shellcheck, format with shfmt, see references/posix-compatibility.md
• Strict mode - Use strict mode and safe defaults, see references/strict-mode.md
• Quoting - Quote all expansions to avoid word splitting, see references/quoting.md
• Functions - Write small, focused functions, see references/functions.md
• Parameter expansion - Set default values and manipulate variables, see references/parameter-expansion.md
• Error handling - Implement exit codes and error messages, see references/error-handling.md
• Idempotency - Make scripts safely re-runnable, see references/idempotency.md

Gotchas

• Unquoted variables word-split and glob-expand — cp $file dest/ silently breaks on filenames with spaces; quote everything
• set -e doesn't catch errors inside if, &&, ||, or pipelines without -o pipefail — combine set -euo pipefail at the top
• [[ ]] is bash/ksh-specific; POSIX sh needs [ ] with different quoting rules — #!/usr/bin/env bash makes the dep explicit
• command -v is portable for checking command existence; which varies across platforms and exits non-zero on missing
• trap ... EXIT runs on normal exit AND on errors with set -e — use it for cleanup; place it BEFORE the code that needs cleanup

Progressive disclosure

• Read references/posix-compatibility.md - Load when ensuring portability across shells
• Read references/strict-mode.md - Load when setting up error handling and safety flags
• Read references/quoting.md - Load when variables expand incorrectly or word splitting occurs
• Read references/functions.md - Load when organizing script logic or creating reusable code
• Read references/parameter-expansion.md - Load when setting default values or manipulating variables
• Read references/error-handling.md - Load when implementing exit codes or error messages
• Read references/argument-parsing.md - Load when parsing command-line flags or arguments
• Read references/validation.md - Load when checking preconditions or input validity
• Read references/idempotency.md - Load when scripts should be safely re-runnable
• Read references/common-patterns.md - Load when learning common shell idioms
• Read references/script-template.md - Load when starting a new shell script