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 |