Linux Basic — Script Header Block

Script Header Block

A good header answers: What does this script do? How do I use it? What does it need?

---

Minimal Template

#!/usr/bin/env bash
#
# backup-database.sh — automated nightly PostgreSQL backup
#
# Usage: backup-database.sh [options]
#   -d DATABASE   database name (default: prod)
#   -o DIR        output directory (default: /backup)
#
# Dependencies: pg_dump, gzip
#
# Exit codes:
#   0 — success
#   1 — backup failed
#   2 — invalid arguments
#
# Author: ops-team@example.com
# Last modified: 2025-04-01

set -euo pipefail

---

Extended Template

For complex scripts, add:

#
# Environment variables:
#   PGPASSWORD — password for pg_dump (required)
#   BACKUP_RETENTION_DAYS — days to keep old backups (default: 7)
#
# Examples:
#   ./backup-database.sh -d mydb -o /mnt/backups
#   PGPASSWORD=secret ./backup-database.sh
#
# See also: restore-database.sh

---

usage() Function

Pair the header with a usage() that the script can print:

usage() {
    cat <<EOF
Usage: $0 [options]
Automated PostgreSQL backup with retention policy.

Options:
  -d DATABASE   database name (default: prod)
  -o DIR        output directory (default: /backup)
  -h            show this help

Examples:
  $0 -d mydb -o /mnt/backups
  PGPASSWORD=secret $0

Exit codes: 0=success, 1=backup failed, 2=invalid args
EOF
    exit "${1:-0}"
}

Call usage 2 when args are invalid, usage 0 for -h.

---

What NOT to Include

• Changelogs — use Git
• Licence boilerplate — link to LICENSE file
• Obvious comments — “This script backs up the database” adds nothing if the filename is backup-database.sh

---

Quick Checklist

• Shebang (#!/usr/bin/env bash)
• One-line description
• Usage with options and defaults
• Dependencies
• Exit codes
• Contact / maintainer
• set -euo pipefail

---

Next → Function Organization