Shell Scripting

Shell Scripting

Overview

Write scripts that are safe by default, easy to read, and predictable across repeated runs. For new scripts, start from assets/script-template.sh.

Workflow

1. Confirm scope and runtime assumptions (bash version, OS expectations, required tools).
2. Start from assets/script-template.sh and adapt it.
3. Keep parsing explicit (-h, --help, --) and fail on unknown flags.
4. Keep operations idempotent where practical (safe re-runs, no destructive defaults).
5. Validate with:
   • bash -n <script>
   • a small functional smoke run with safe inputs

Output Style

Use structured output helpers:

• log_error: red + bold prefix (ERROR:), stderr
• log_warn: yellow, stderr
• log_note: dim informational note
• log_success: green success output

Use ANSI styling only when interactive:

• enable color when -t 1 or -t 2
• disable color when TERM=dumb or NO_COLOR is set

Keep usage output readable:

• bold section headers (Usage, Options, Examples)
• highlight command examples in cyan
• keep notes concise and actionable

Core Practices

• Use #!/usr/bin/env bash and set -euo pipefail.
• Quote variable expansions unless intentionally using word splitting.
• Use local for function-scoped variables.
• Prefer printf over echo for structured output.
• Validate required commands early (for example with command -v checks).
• Use mktemp for temporary files/dirs and cleanup with trap.
• Avoid destructive actions by default; require explicit opt-in for risky actions.
• Keep scripts composable and testable with small functions.

Resources

• assets/script-template.sh: baseline script template with rich usage/log output.
• references/best-practices.md: expanded checklist and patterns.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.