Shell

Shell Scripts Best Practices (Community)

Comprehensive best practices guide for shell scripting, designed for AI agents and LLMs. Contains 49 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 [blocked] - Prevent command injection from user input
• safety-eval-avoidance [blocked] - Avoid eval for dynamic commands
• safety-absolute-paths [blocked] - Use absolute paths for external commands
• safety-temp-files [blocked] - Create secure temporary files
• safety-suid-forbidden [blocked] - Never use SUID/SGID on shell scripts
• safety-argument-injection [blocked] - Prevent argument injection with double dash

2. Portability (CRITICAL)

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

3. Error Handling (HIGH)

• err-strict-mode [blocked] - Use strict mode for error detection
• err-exit-codes [blocked] - Use meaningful exit codes
• err-trap-cleanup [blocked] - Use trap for cleanup on exit
• err-stderr-messages [blocked] - Send error messages to stderr
• err-pipefail [blocked] - Use pipefail to catch pipeline errors
• err-check-commands [blocked] - Check command success explicitly
• err-shellcheck [blocked] - Use ShellCheck for static analysis
• err-debug-tracing [blocked] - Use debug tracing with set -x and PS4

4. Variables & Data (HIGH)

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

5. Quoting & Expansion (MEDIUM-HIGH)

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

6. Functions & Structure (MEDIUM)

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

7. Testing & Conditionals (MEDIUM)

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

8. Performance (LOW-MEDIUM)

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

9. Style & Formatting (LOW)

• style-indentation [blocked] - Use consistent indentation
• style-file-structure [blocked] - Follow consistent file structure
• style-comments [blocked] - Write useful comments

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions [blocked] - Category structure and impact levels
• Rule template [blocked] - Template for adding new rules

Reference Files

Key Sources

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