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
| Priority | Category | Impact | Prefix | Rules |
|---|---|---|---|---|
| 1 | Safety & Security | CRITICAL | safety- | 6 |
| 2 | Portability | CRITICAL | port- | 5 |
| 3 | Error Handling | HIGH | err- | 6 |
| 4 | Variables & Data | HIGH | var- | 5 |
| 5 | Quoting & Expansion | MEDIUM-HIGH | quote- | 6 |
| 6 | Functions & Structure | MEDIUM | func- | 5 |
| 7 | Testing & Conditionals | MEDIUM | test- | 5 |
| 8 | Performance | LOW-MEDIUM | perf- | 6 |
| 9 | Style & Formatting | LOW | style- | 4 |
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
| File | Description |
|---|---|
| AGENTS.md | Complete compiled guide with all rules |
| references/_sections.md | Category definitions and ordering |
| assets/templates/_template.md | Template for new rules |
| metadata.json | Version and reference information |