cofin/bash

Bash Scripting

Overview

Bash is the default shell on most Linux distributions. This skill covers idiomatic scripting patterns following the Google Shell Style Guide, with emphasis on safety, readability, and maintainability.

Quick Reference

Safety Header (always include)

#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'

| Flag | Effect | |------|--------| | set -e | Exit immediately on non-zero return | | set -u | Error on unset variables | | set -o pipefail | Pipe returns rightmost non-zero exit code | | IFS=$'\n\t' | Safer word splitting (no space splitting) |

Style Essentials

| Rule | Good | Bad | |------|------|-----| | Function declaration | my_func() { ... } | function my_func { ... } | | Local variables | local file_path="$1" | file_path=$1 | | Constants | readonly MAX_RETRIES=3 | MAX_RETRIES=3 | | Variable expansion | "${var}" | $var | | Command substitution | "$(command)" | `command` | | Declare + assign | local out; out="$(cmd)" | local out="$(cmd)" | | File test | [[ -f "${file}" ]] | [ -f $file ] |

Common ShellCheck Fixes

| Code | Issue | Fix | |------|-------|-----| | SC2086 | Unquoted variable | Double-quote: "${var}" | | SC2046 | Unquoted command sub | Quote or use mapfile | | SC2155 | Declare and assign together | Separate into two statements | | SC2034 | Unused variable | Add export or # shellcheck disable=SC2034 |

<workflow>

Workflow

Step 1: Start with the Safety Header

Every script begins with the shebang, strict mode, and a usage comment block describing purpose, usage, and examples.

Step 2: Define Functions

Organize logic into functions. Use local for all function-scoped variables. Use main() as the entry point, called at the bottom with main "$@".

Step 3: Handle Arguments

Use getopts for simple flags, or manual while [[ $# -gt 0 ]] parsing for long options. Always validate required arguments and print usage on error.

Step 4: Add Cleanup Traps

Use trap cleanup EXIT for any script that creates temporary files, acquires locks, or needs to restore state on failure.

Step 5: Run ShellCheck

Validate the script with shellcheck script.sh before committing. Fix all warnings; disable specific rules only with a justifying comment.

</workflow> <guardrails>

Guardrails

• Always quote variables — unquoted variables cause word splitting and glob expansion bugs; use "${var}" everywhere
• Always use ShellCheck — run shellcheck on every script; it catches the majority of common bash pitfalls
• Prefer functions over inline code — functions with local variables prevent accidental global state leaks
• Never use eval unless absolutely necessary — it is the most common source of injection vulnerabilities in shell scripts
• Use [[ ]] not [ ] — double brackets prevent word splitting and support regex matching
• Use mktemp for temporary files — never hardcode /tmp/myscript.tmp; it creates race conditions
• Avoid parsing ls output — use globs (*.txt) or find with -print0 and read -d '' for safe file iteration

</guardrails> <validation>

Validation Checkpoint

Before delivering a script, verify:

• [ ] Script starts with #!/usr/bin/env bash and set -euo pipefail
• [ ] All variables are quoted with "${var}"
• [ ] All function variables use local
• [ ] trap cleanup EXIT is set if the script creates temporary resources
• [ ] ShellCheck passes with no unacknowledged warnings
• [ ] Script has a usage/help function accessible via -h or --help

</validation> <example>

Example

A safe script template with error handling, argument parsing, and cleanup:

#!/usr/bin/env bash
#
# Deploy an application to the target environment.
#
# Usage:
#   deploy.sh [-v] [-e environment] <app_name>
#
set -euo pipefail
IFS=$'\n\t'

readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly TMPDIR="$(mktemp -d)"

cleanup() {
    rm -rf "${TMPDIR}"
}
trap cleanup EXIT

usage() {
    cat <<EOF
Usage: $(basename "$0") [-v] [-e environment] <app_name>

Options:
  -v              Verbose output
  -e ENVIRONMENT  Target environment (default: staging)
  -h              Show this help
EOF
}

main() {
    local verbose=false
    local environment="staging"

    while getopts ":ve:h" opt; do
        case "${opt}" in
            v) verbose=true ;;
            e) environment="${OPTARG}" ;;
            h) usage; exit 0 ;;
            :) echo "Error: -${OPTARG} requires an argument" >&2; exit 1 ;;
            ?) echo "Error: Unknown option -${OPTARG}" >&2; exit 1 ;;
        esac
    done
    shift $((OPTIND - 1))

    if [[ $# -eq 0 ]]; then
        echo "Error: app_name is required" >&2
        usage >&2
        exit 1
    fi

    local app_name="$1"

    if [[ "${verbose}" == true ]]; then
        echo "Deploying ${app_name} to ${environment}..."
    fi

    # Build and deploy logic here
    echo "Deployed ${app_name} to ${environment} successfully."
}

main "$@"

</example>

---

References Index

For detailed guides and code examples, refer to the following documents in references/:

• Style Guide
  • Google Shell Style Guide patterns: file headers, function naming, variable naming, quoting rules, error handling.
• Common Patterns
  • Argument parsing (getopts), trap for cleanup, here-docs, process substitution, array manipulation, associative arrays.
• Safety & Defensive Scripting
  • Shellcheck compliance, avoiding common pitfalls, handling spaces in filenames, proper exit codes, signal handling.

---

Official References

• https://google.github.io/styleguide/shellguide.html
• https://www.gnu.org/software/bash/manual/

Shared Styleguide Baseline

• Use shared styleguides for generic language/framework rules to reduce duplication in this skill.
• General Principles
• Bash
• Keep this skill focused on tool-specific workflows, edge cases, and integration details.