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