Shell Scripts Best Practices

Comprehensive best practices guide for shell scripting, designed for AI agents and LLMs. Contains 48 rules across 9 categories, prioritized by impact from critical (safety, portability) to incremental (style). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics.

When to Apply

Reference these guidelines when:

• Writing new bash or POSIX shell scripts
• Reviewing shell scripts for security vulnerabilities
• Debugging scripts that fail silently or behave unexpectedly
• Porting scripts between Linux, macOS, and containers
• Optimizing shell script performance
• Setting up CI/CD pipelines with shell scripts

Rule Categories by Priority

Quick Reference

1. Safety & Security (CRITICAL)

• safety-command-injection – Prevent command injection from user input
• safety-eval-avoidance – Avoid eval for dynamic commands
• safety-absolute-paths – Use absolute paths for external commands
• safety-temp-files – Create secure temporary files
• safety-suid-forbidden – Never use SUID/SGID on shell scripts
• safety-argument-injection – Prevent argument injection with double dash

2. Portability (CRITICAL)

• port-shebang-selection – Choose shebang based on portability needs
• port-avoid-bashisms – Avoid bashisms in POSIX scripts
• port-printf-over-echo – Use printf instead of echo for portability
• port-export-syntax – Use portable export syntax
• port-test-portability – Use portable test constructs

3. Error Handling (HIGH)

• err-strict-mode – Use strict mode for error detection
• err-exit-codes – Use meaningful exit codes
• err-trap-cleanup – Use trap for cleanup on exit
• err-stderr-messages – Send error messages to stderr
• err-pipefail – Use pipefail to catch pipeline errors
• err-check-commands – Check command success explicitly

4. Variables & Data (HIGH)

• var-use-arrays – Use arrays for lists instead of strings
• var-local-scope – Use local for function variables
• var-naming-conventions – Follow variable naming conventions
• var-readonly-constants – Use readonly for constants
• var-default-values – Use parameter expansion for defaults

5. Quoting & Expansion (MEDIUM-HIGH)

• quote-always-quote-variables – Always quote variable expansions
• quote-dollar-at – Use “$@” for argument passing
• quote-command-substitution – Quote command substitutions
• quote-brace-expansion – Use braces for variable clarity
• quote-here-documents – Use here documents for multi-line strings
• quote-glob-safety – Control glob expansion explicitly

6. Functions & Structure (MEDIUM)

• func-main-pattern – Use main() function pattern
• func-single-purpose – Write single-purpose functions
• func-return-values – Use return values correctly
• func-documentation – Document functions with header comments
• func-avoid-aliases – Prefer functions over aliases

7. Testing & Conditionals (MEDIUM)

• test-double-brackets – Use [[ ]] for tests in bash
• test-arithmetic – Use (( )) for arithmetic comparisons
• test-explicit-empty – Use explicit empty/non-empty string tests
• test-file-operators – Use correct file test operators
• test-case-patterns – Use case for pattern matching

8. Performance (LOW-MEDIUM)

• perf-builtins-over-external – Use builtins over external commands
• perf-avoid-subshells – Avoid unnecessary subshells
• perf-process-substitution – Use process substitution for temp files
• perf-read-files – Read files efficiently
• perf-parameter-expansion – Use parameter expansion for string operations
• perf-batch-operations – Batch operations instead of loops

9. Style & Formatting (LOW)

• style-indentation – Use consistent indentation
• style-file-structure – Follow consistent file structure
• style-comments – Write useful comments
• style-shellcheck – Use ShellCheck for static analysis

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions – Category structure and impact levels
• Rule template – Template for adding new rules

Reference Files

Key Sources

• Google Shell Style Guide
• ShellCheck
• Greg’s Wiki (wooledge.org)
• POSIX Shell Specification