shell-scripting

Bash Scripting Best Practices

Guidance for writing reliable, maintainable bash scripts following modern best practices. Emphasises simplicity, automated tooling, and defensive programming without over-engineering.

When to Use Shell (and When Not To)

Use Shell For:

• Small utilities and simple wrapper scripts (<100 lines)
• Orchestrating other programmes and tools
• Simple automation tasks
• Build/deployment scripts with straightforward logic
• Quick data transformation pipelines

Do NOT Use Shell For:

• Complex business logic or data structures
• Performance-critical code
• Scripts requiring extensive error handling
• Anything over ~100 lines or with non-straightforward control flow
• When you need proper data structures beyond arrays

Critical: If your script grows too large (1000+ lines) or complex, consider offering to rewrite it in a proper language (Python, Go, etc.) before it becomes unmaintainable.

Mandatory Foundations

Every bash script must have these elements:

1. Proper Shebang

#!/usr/bin/env bash

Why: Portable across systems where bash may not be at /bin/bash (e.g., macOS, BSD, NixOS).

Alternative: #!/bin/bash if you know the script only runs on Linux and prefer explicit paths.

2. Strict Mode

set -euo pipefail

What each flag does:

• -e: Exit immediately if any command fails (non-zero exit)
• -u: Treat unset variables as errors
• -o pipefail: Pipe fails if ANY command in pipeline fails (not just the last)

When to add -x: Only for debugging, not in production scripts (makes output noisy).

3. ShellCheck Compliance

Run ShellCheck on EVERY script before committing:

shellcheck script.sh

Fix all warnings. ShellCheck catches:

• Unquoted variables
• Deprecated syntax
• Common bugs and pitfalls
• Portability issues

4. Basic Script Structure

#!/usr/bin/env bash
set -euo pipefail

# Brief description of what this script does

# Simple error reporting
die() {
    echo "Error: ${1}" >&2
    exit 1
}

# Your code here