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

Priority Category Impact Prefix Rules

1 Safety & Security CRITICAL safety-

6

2 Portability CRITICAL port-

5

3 Error Handling HIGH err-

8

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-

3

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

• err-shellcheck

• Use ShellCheck for static analysis

• err-debug-tracing

• Use debug tracing with set -x and PS4

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

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

Key Sources

• Google Shell Style Guide

• ShellCheck

• Greg's Wiki (wooledge.org)

• POSIX Shell Specification