Bash Style Guide

Scope Boundaries

• Use this skill when the task matches the trigger condition described in

  description

  .
• Do not use this skill when the primary task falls outside this skill's domain.

Trigger And Co-activation Reference

• If available, use

  references/trigger-matrix.md

  for canonical co-activation rules.
• If available, resolve style-guide activation from changed files with

  python3 scripts/resolve_style_guides.py <changed-path>...

  .
• If available, validate trigger matrix consistency with

  python3 scripts/validate_trigger_matrix_sync.py

  .

Quality Gate Command Reference

• If available, use

  references/quality-gate-command-matrix.md

  for CI check-only and local autofix mapping.

Quick Start Snippets

Script skeleton with strict mode and cleanup trap

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

readonly SCRIPT_NAME="$(basename "$0")"
readonly TEMP_DIR="$(mktemp -d)"

cleanup() {
  rm -rf -- "${TEMP_DIR}"
}

on_error() {
  local line="$1"
  local exit_code="$2"
  echo "${SCRIPT_NAME}: failed at line ${line} (exit=${exit_code})" >&2
}

trap cleanup EXIT
trap 'on_error "$LINENO" "$?"' ERR

main() {
  echo "working dir: ${TEMP_DIR}"
}

main "$@"

Required environment variable check (fail fast)

: "${API_TOKEN:?API_TOKEN is required}"
: "${API_BASE_URL:?API_BASE_URL is required}"

Safe command assembly with arrays

run_curl() {
  local url="$1"
  local -a args=(
    --fail
    --silent
    --show-error
    --header "Authorization: Bearer ${API_TOKEN}"
    "${url}"
  )

  curl "${args[@]}"
}

Bounded retry with explicit backoff constants

readonly MAX_ATTEMPTS=5
readonly RETRY_DELAY_SECONDS=2

retry_command() {
  local attempt=1
  while (( attempt <= MAX_ATTEMPTS )); do
    if "$@"; then
      return 0
    fi

    if (( attempt == MAX_ATTEMPTS )); then
      echo "command failed after ${MAX_ATTEMPTS} attempts" >&2
      return 1
    fi

    sleep "${RETRY_DELAY_SECONDS}"
    ((attempt++))
  done
}

Safe line reading preserving whitespace

while IFS= read -r line; do
  printf 'line=%s\n' "${line}"
done < "${input_file}"

Structure And Readability

1. Use

   #!/usr/bin/env bash

   for executable scripts.
2. For executable entrypoints, use strict mode:

   set -euo pipefail

   .
3. Keep functions focused on one responsibility and use

   main

   for orchestration.
4. Use uppercase constants (

   MAX_RETRIES

   ) and lowercase locals (

   retry_count

   ).
5. Use

   local

   inside functions to avoid state leakage.
6. Add short intent comments only for non-obvious logic.

Data Handling And Quoting

1. Quote expansions by default:

   "${var}"

   ,

   "${array[@]}"

   .
2. Use arrays for argument lists; avoid string-concatenated command assembly.
3. Replace magic numbers with named constants including units (

   TIMEOUT_SECONDS

   ).
4. Avoid

   eval

   ; treat it as a security-sensitive last resort.
5. Fail fast for required environment variables; do not add silent defaults for required config.

Error Handling And Control Flow

1. Return explicit non-zero codes for expected failure modes.
2. Use

   trap

   for cleanup and actionable error reporting.
3. Handle failure paths intentionally (

   if ! cmd; then ... fi

   ) instead of masking.
4. Avoid broad

   || true

   ; suppress only with explicit rationale.
5. Let failures surface when root cause should be fixed.

Security And Operational Safety

1. Validate all external input before use.
2. Use

   --

   before positional paths in destructive commands (

   rm -- "$target"

   ).
3. Prefer

   mktemp

   for temporary files/directories.
4. Never print secrets or tokens in logs.
5. Use least privilege and avoid unnecessary

   sudo

   .

Performance And Scalability

1. Avoid subshell spawning in tight loops when builtins suffice.
2. Prefer single-pass text processing over repeated pipelines.
3. Batch filesystem operations where practical.
4. Use bounded retry loops with named backoff constants.

Testing And Verification

1. Add

   bats

   tests for critical behavior and failure paths.
2. Cover edge cases: empty input, whitespace paths, missing env vars, timeout, retry exhaustion.
3. Document manual verification where automation is not feasible.
4. Check idempotency for scripts that may run repeatedly.

Minimal

bats

example

#!/usr/bin/env bats

@test "fails when required env var is missing" {
  run ./script.sh
  [ "$status" -ne 0 ]
  [[ "$output" == *"API_TOKEN is required"* ]]
}

CI Required Quality Gates (check-only)

1. Run

   shellcheck

   with warnings treated as actionable.
2. Run

   shfmt -d

   (or equivalent check mode) and require zero diff.
3. Run test suite (

   bats test/

   or repository-specific path).
4. Reject changes that hide failures or rely on implicit behavior.

Optional Autofix Commands (local)

1. Run

   shfmt -w

   .
2. Apply safe mechanical fixes suggested by

   shellcheck

   , then rerun checks.