Shell Style Guide

When to Use Shell

Shell MAY be appropriate for:

• Small utilities under 100 lines
• Simple wrapper scripts
• Glue between other programs
• Build/CI scripts

Scripts MUST NOT exceed 100 lines. If your script grows beyond 100 lines or needs complex logic, you MUST rewrite it in Python.

Linting: shellcheck

You MUST use shellcheck² for linting shell scripts.

Configuration

You SHOULD create a .shellcheckrc file:

# Enable all checks
enable=all

# Exclude specific rules if needed
# disable=SC2086

Formatting: shfmt

You MUST use shfmt³ for formatting shell scripts.

Why shfmt

shfmt provides consistent, automated formatting for shell scripts, eliminating style debates and ensuring readability across your codebase. It handles complex cases like heredocs and pipeline formatting correctly.

# Install
go install mvdan.cc/sh/v3/cmd/shfmt@v3.12.0

# Format
shfmt -w script.sh

# Format with specific style
shfmt -i 2 -ci -bn -w script.sh

You MUST use these options:

• -i 2: 2-space indent
• -ci: Indent switch cases
• -bn: Binary ops on newline

Script Template

All scripts MUST follow this template structure:

#!/bin/bash
#
# Brief description of what this script does.

set -Eeuo pipefail

# Constants
# Assign first, then mark readonly: a combined `readonly x="$(...)"` reports
# readonly's own status and hides a failed substitution from `set -e`.
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_DIR

# Cleanup
cleanup() {
  local exit_code=$?
  # Add cleanup logic here
  exit "${exit_code}"
}
trap cleanup EXIT ERR

# Functions
log() {
  local timestamp
  timestamp="$(date +'%Y-%m-%dT%H:%M:%S%z')"
  echo "[${timestamp}] $*"
}

err() {
  local timestamp
  timestamp="$(date +'%Y-%m-%dT%H:%M:%S%z')"
  echo "[${timestamp}] ERROR: $*" >&2
}

usage() {
  cat <<EOF
Usage: $(basename "$0") [OPTIONS] <argument>

Description of what this script does.

Options:
  -h, --help     Show this help message
  -v, --verbose  Enable verbose output

Examples:
  $(basename "$0") input.txt
  $(basename "$0") -v input.txt
EOF
}

main() {
  local verbose=false

  while [[ $# -gt 0 ]]; do
    case "$1" in
      -h | --help)
        usage
        exit 0
        ;;
      -v | --verbose)
        verbose=true
        shift
        ;;
      *)
        break
        ;;
    esac
  done

  if [[ $# -lt 1 ]]; then
    err "Missing required argument"
    usage
    exit 1
  fi

  local input="$1"

  if [[ "${verbose}" == true ]]; then
    log "Running from: ${SCRIPT_DIR}"
    log "Processing: ${input}"
  fi

  # Main logic here
}

main "$@"

The template is executable documentation: it MUST pass shellcheck under the enable=all configuration above and shfmt -i 2 -ci -bn -d unmodified. Copy it verbatim and delete what you do not need.

Shebang and Options

All scripts MUST include:

#!/bin/bash
set -Eeuo pipefail

• set -E: Inherit ERR trap in functions (REQUIRED)
• set -e: Exit on error (REQUIRED)
• set -u: Error on undefined variables (REQUIRED)
• set -o pipefail: Pipelines fail on first error (REQUIRED)

Variables

You MUST follow these variable conventions:

# Use braces and quotes (REQUIRED)
echo "${variable}"

# Local variables in functions (REQUIRED)
my_function() {
  local my_var="value"
}

# Constants are uppercase (REQUIRED)
readonly MAX_RETRIES=3
declare -r CONFIG_FILE="/etc/myapp.conf"

Tests

You MUST use [[ ]] for tests, not [ ]:

# Use [[ ]] not [ ] (REQUIRED)
if [[ "${var}" == "value" ]]; then
  echo "match"
fi

# String tests
if [[ -z "${var}" ]]; then  # Empty
if [[ -n "${var}" ]]; then  # Not empty

# File tests
if [[ -f "${file}" ]]; then  # File exists
if [[ -d "${dir}" ]]; then   # Directory exists

Command Substitution

You MUST use $() for command substitution, not backticks:

# Use $() not backticks (REQUIRED)
result="$(command)"
nested="$(command "$(other_command)")"

Trap-Based Cleanup

Scripts SHOULD implement cleanup handlers for reliable resource management:

# Holds only this script's own temporary directory; empty until mktemp succeeds.
tmp_dir=''

cleanup() {
  local exit_code=$?
  if [[ -n "${tmp_dir}" && -d "${tmp_dir}" ]]; then
    rm -rf -- "${tmp_dir}"
  fi
  exit "${exit_code}"
}

trap cleanup EXIT ERR

A cleanup handler MUST delete only paths the script itself created, and MUST NOT recursively delete TMPDIR or any other inherited path:

# Don't: TMPDIR is the caller's temporary root, which the script did not create
rm -rf -- "${TMPDIR:-}"

# Do: delete only the allocation this script owns
if [[ -n "${tmp_dir}" && -d "${tmp_dir}" ]]; then
  rm -rf -- "${tmp_dir}"
fi

Safe Temporary Files

You SHOULD use mktemp with the cleanup trap above for temporary files. Register the trap first, then allocate, so an allocation failure leaves tmp_dir empty and cleanup inert:

tmp_dir="$(mktemp -d)" || {
  err "Failed to create temp dir"
  exit 1
}

Dependency Checking

Scripts SHOULD verify required commands exist before use:

check_deps() {
  local -a missing=()
  for cmd in "$@"; do
    command -v "$cmd" >/dev/null 2>&1 || missing+=("$cmd")
  done
  if [[ ${#missing[@]} -gt 0 ]]; then
    err "Missing dependencies: ${missing[*]}"
    exit 1
  fi
}

check_deps jq curl git

Note: Use command -v instead of which—it’s a shell builtin and more portable.

Testing: bats

You SHOULD use bats⁴ (Bash Automated Testing System) for testing shell scripts.

Project Structure

project/
├── bin/
│   └── script.sh      # executable; ends with main "$@", never sourced
├── lib/
│   └── helpers.sh     # sourceable functions only, no main call
├── tests/
│   ├── script.bats
│   ├── test_helper.sh
│   └── fixtures/
└── README.md

Executables and libraries MUST be separate files. An executable that ends with main "$@" MUST NOT be sourced by a test; only files that define functions and call nothing MAY be sourced.

# lib/helpers.sh
slugify() {
  local text="$1"
  printf '%s' "${text,,}" | tr -cs 'a-z0-9' '-'
}

CI Integration

Workflow examples in this guide are complete files. Each MUST declare an on trigger, grant only permissions: contents: read, set a finite timeout-minutes, and cancel superseded runs through concurrency:

# .github/workflows/test.yml
name: Shell Tests

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install bats
        run: npm install --global bats@1.13.0
      - name: Run tests
        run: bats tests/

Coverage: bashcov

You MAY use bashcov⁵ for code coverage of shell scripts.

# Install
gem install bashcov

# Run with bats
bashcov bats tests/

# With simplecov output
bashcov --root . bats tests/

Pre-commit Configuration

You SHOULD configure pre-commit hooks⁸:

repos:
  - repo: https://github.com/shellcheck-py/shellcheck-py
    rev: v0.11.0.1
    hooks:
      - id: shellcheck

  - repo: https://github.com/scop/pre-commit-shfmt
    rev: v3.12.0-2
    hooks:
      - id: shfmt
        args: [-i, "2", -ci, -bn]

CI Pipeline

You SHOULD integrate shell linting into your CI pipeline⁹:

# .github/workflows/lint.yml
name: Shell Lint

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: shellcheck
        uses: ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38 # 2.0.0
        with:
          scandir: './scripts'
      - name: Install shfmt
        env:
          SHFMT_VERSION: 3.14.1
          SHFMT_SHA256: 76e77641faa025814b77f153b29796b8e6fa2fca03e0c76a691608b86c7ea7bf
        run: |
          base=https://github.com/mvdan/sh/releases/download
          curl -fsSL -o /tmp/shfmt \
            "${base}/v${SHFMT_VERSION}/shfmt_v${SHFMT_VERSION}_linux_amd64"
          echo "${SHFMT_SHA256}  /tmp/shfmt" | sha256sum --check --strict
          mkdir -p "${HOME}/.local/bin"
          install -m 0755 /tmp/shfmt "${HOME}/.local/bin/shfmt"
          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
      - name: shfmt
        run: shfmt -i 2 -ci -bn -d .

You MUST NOT use uses: mvdan/sh@v0.7. The mvdan/sh repository publishes no action at any tag, and v0.7 does not exist, so the step fails to resolve before it runs.