Shell Scripting Guide

This guide uses the Homebrew automation scripts as practical, real-world examples to teach shell scripting concepts. Rather than learning from contrived examples, you will study code that solves actual problems — automating package management, detecting system architecture, handling errors gracefully, and building interactive tools. Each section builds on the previous one, taking you from fundamental concepts through to professional-level patterns.

1. Basic Script Structure

Every well-written shell script begins with a consistent structure that establishes the execution environment, documents the script's purpose, and sets up error handling. Getting this foundation right is essential because it determines how reliably your script behaves across different systems and under different conditions.

The Shebang Line

The very first line of any shell script is the shebang (also called a hashbang). This special comment tells the operating system which interpreter should execute the script. Without it, the system would not know whether your file is a Bash script, a Python script, or something else entirely.

#!/usr/bin/env bash

You might wonder why we use #!/usr/bin/env bash instead of the simpler #!/bin/bash. The answer is portability. On most macOS systems, /bin/bash is an older version of Bash (3.2), while a newer version installed via Homebrew lives at /opt/homebrew/bin/bash or /usr/local/bin/bash. By using env, the script finds whichever bash executable appears first in the user's PATH, which is typically the most up-to-date version available.

Script Metadata

After the shebang, professional scripts include a metadata block that describes the script's purpose, author, version, and license. This block is formatted as comments and serves as built-in documentation for anyone who opens the file.

###############################################################################
# Script Name: brew_setup_tahoe.sh
# Description: Educational Homebrew installer with interactive setup
# Version:     3.0.0
# Author:      CodeCraftedApps
# License:     MIT
###############################################################################

This metadata is not just decoration. When someone encounters your script months or years later — possibly yourself — this header immediately communicates what the script does, who wrote it, and what rules govern its use. It takes seconds to write and saves significant time when maintaining or debugging scripts.

Strict Error Handling

One of the most important lines in any production shell script is the error handling configuration. Bash's default behavior is surprisingly permissive: it silently ignores failed commands and continues executing. This is almost never what you want in an automation script, where a failed step could mean downstream operations are working with bad data or missing prerequisites.

set -euo pipefail

This single line enables three critical protections:

• set -e (errexit) — Exit immediately if any command returns a non-zero status. Without this, your script would happily continue running even after a command fails, potentially compounding the problem.
• set -u (nounset) — Treat unset variables as an error rather than silently expanding to an empty string. This catches typos in variable names, which are one of the most common and frustrating bugs in shell scripts.
• set -o pipefail — If any command in a pipeline fails, the entire pipeline's exit status reflects that failure. Without this, only the last command's exit status is considered, meaning errors in earlier pipeline stages are silently ignored.

Together, these flags transform Bash from a forgiving interactive shell into a strict scripting language that fails fast and loud, which is exactly the behavior you want when automating system operations. If an error occurs, you want to know about it immediately rather than discovering the consequences later.

2. Variables and Configuration

Variables are the foundation of any configurable script. Shell scripting distinguishes between constants (values that should never change during execution) and variables (values that may be modified). Understanding this distinction and using the right type for each situation makes your scripts more robust and easier to reason about.

Constants

Constants are values determined at script startup that remain fixed throughout execution. In Bash, you declare constants using the readonly keyword, which prevents them from being accidentally reassigned later in the script. Common constants include the script's directory path, project root, and configuration file locations.

# Constants (readonly) — determined at startup, never change
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
readonly VERSION="3.0.0"
readonly LOG_FILE="$HOME/Library/Logs/HomebrewSetup.log"

The SCRIPT_DIR pattern deserves special attention. It uses BASH_SOURCE[0] to find the actual location of the script file, then resolves it to an absolute path using cd and pwd. This works correctly regardless of how the script was invoked — whether by absolute path, relative path, or via a symlink. This is a pattern you will use frequently and is worth memorizing.

Arrays

Bash supports two types of arrays: indexed arrays (regular lists) and associative arrays (key-value pairs, like dictionaries in other languages). Arrays are essential for managing lists of items such as applications to install, configuration file locations, or required commands to check.

# Regular arrays — ordered lists of values
CONFIG_LOCATIONS=(
    "$PROJECT_ROOT/config/homebrew-scripts.conf"
    "$HOME/.config/homebrew-scripts/config.conf"
)

# Associative arrays — key-value pairs for structured data
declare -A CUSTOM_APPS=(
    ["visual-studio-code"]="Visual Studio Code:development"
    ["docker"]="Docker Desktop:development"
    ["slack"]="Slack:communication"
    ["1password"]="1Password:utilities"
)

The associative array example shows a common pattern for encoding multiple pieces of information in a single data structure. Each key is the Homebrew package name, and the value contains the display name and category separated by a colon. This lets the script look up both the human-readable name and the category for any package by its identifier.

Variables

Unlike constants, variables may change during script execution. They are used for counters, status tracking, and accumulating results. Always initialize variables with sensible defaults to avoid issues with set -u (the nounset option from our strict error handling).

# Variables (can change during execution)
CURRENT_STEP=0
TOTAL_STEPS=8
INSTALL_COUNT=0
ERROR_COUNT=0
DRY_RUN=false

3. Functions and Modularity

Functions are the building blocks of maintainable shell scripts. By encapsulating logic into discrete, named units, you create code that is easier to read, test, debug, and reuse. In the Brew Scripts project, functions are organized into a shared library (lib/common.sh) that all scripts can import, eliminating code duplication and ensuring consistent behavior.

Function Design Principles

Every function should follow the Single Responsibility Principle: it should do one thing and do it well. The function's name should clearly communicate its purpose, and its inputs and outputs should be well-defined. Here is an example that validates an email address:

# Good: Single responsibility, clear name, parameter validation
validate_email() {
    local email="$1"

    # Input validation — reject empty strings immediately
    if [[ -z "$email" ]]; then
        return 1
    fi

    # Business logic — check against a regex pattern
    if [[ "$email" =~ ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$ ]]; then
        return 0
    else
        return 1
    fi
}

Notice several important patterns in this function. First, it uses local to declare its variables. Without local, variables would be global, potentially overwriting values used by the calling code. This is one of the most common sources of subtle bugs in shell scripts. Second, it validates its input before doing any work. Third, it communicates success or failure through return codes (0 for success, non-zero for failure) rather than printing output, which makes it composable with other functions.

Function Libraries

When you have functions that are used by multiple scripts, extract them into a shared library file. The source command (or its synonym .) loads the library's functions into the current script's environment, making them available for use.

# Source external functions from a shared library
if [[ -f "$LIB_DIR/common.sh" ]]; then
    # shellcheck source=lib/common.sh
    source "$LIB_DIR/common.sh"
else
    echo "ERROR: Common library not found at $LIB_DIR/common.sh" >&2
    exit 1
fi

The # shellcheck source= comment is a directive for ShellCheck, the static analysis tool for shell scripts. It tells ShellCheck where to find the sourced file so it can check function calls and variable references across files. The defensive check for the library file's existence ensures that the script fails with a clear error message rather than a confusing "command not found" error if the library is missing.

Key Design Concepts

• Single Responsibility — Each function should do exactly one thing. If you find yourself adding "and" to a function's description, it probably needs to be split into two functions.
• Parameter Validation — Always check that inputs are valid before processing them. Catching bad input at the function boundary is much easier than debugging the effects of invalid data flowing through multiple layers of logic.
• Return Codes — Use return code 0 for success and non-zero for failure. This is the universal convention in Unix systems, and it allows your functions to work seamlessly with if statements, &&/|| operators, and set -e.
• Local Variables — Always use local for variables inside functions. Global variables in shell scripts are a recipe for hard-to-find bugs, especially as your script grows larger.

4. User Input and Interaction

Interactive scripts need to communicate clearly with the user and handle a wide variety of inputs gracefully. Users will type unexpected things, press enter without typing anything, and make mistakes. A well-designed interactive function anticipates all of these scenarios and handles them without crashing or producing confusing results.

Interactive Prompts with Validation

The ask_yes_no function is a cornerstone of the Brew Scripts interactive experience. It presents a yes/no question to the user, handles default values, validates the response, and loops until it gets a valid answer.

ask_yes_no() {
    local prompt="$1"
    local default="${2:-y}"

    while true; do
        if [[ "$default" == "y" ]]; then
            echo -ne "${YELLOW}$prompt [Y/n]: ${NC}"
        else
            echo -ne "${YELLOW}$prompt [y/N]: ${NC}"
        fi

        read -r response
        response=${response,,}  # Convert to lowercase

        case "$response" in
            ""|"y"|"yes")
                [[ "$default" == "y" || "$response" != "" ]] && return 0 || return 1
                ;;
            "n"|"no")
                return 1
                ;;
            *)
                echo -e "${RED}Please answer yes or no.${NC}"
                ;;
        esac
    done
}

This function demonstrates several important interactive scripting techniques. The ${2:-y} syntax provides a default value if the second argument is not supplied. The ${response,,} syntax converts the response to lowercase, so "Yes," "YES," and "yes" are all treated the same way. The case statement handles multiple possible inputs clearly, and the while true loop ensures the user cannot proceed until they provide a valid answer.

Color Coding

Color makes terminal output dramatically easier to read. The Brew Scripts project defines color constants at the top of the script and uses them consistently throughout to signal different types of information: yellow for prompts, green for success, red for errors, and blue for informational messages.

# Define color constants for terminal output
readonly RED='\033[0;31m'
readonly GREEN='\033[0;32m'
readonly YELLOW='\033[1;33m'
readonly BLUE='\033[0;34m'
readonly NC='\033[0m'  # No Color — resets to default

# Usage examples
echo -e "${GREEN}[SUCCESS]${NC} Application installed"
echo -e "${RED}[ERROR]${NC} Installation failed"
echo -e "${YELLOW}[WARNING]${NC} Skipping optional step"
echo -e "${BLUE}[INFO]${NC} Checking system requirements..."

Always use the NC (No Color) reset code after colored text. Without it, all subsequent terminal output would inherit the last color set, which can make the entire terminal display unreadable. The -e flag on echo enables interpretation of these escape sequences.

5. Error Handling and Validation

Robust error handling separates amateur scripts from professional-grade automation. In a production environment, network connections drop, disks fill up, permissions change, and commands that worked yesterday fail today. Your script needs to anticipate these situations and respond intelligently rather than simply crashing.

Defensive Programming

Defensive programming means checking prerequisites before attempting operations. The check_prerequisites function examines the system environment at startup, identifies all issues, and reports them together rather than failing on the first problem found. This saves the user from a frustrating cycle of fixing one issue, rerunning, finding the next issue, and repeating.

check_prerequisites() {
    local errors=0

    # Check operating system
    if [[ "$(uname)" != "Darwin" ]]; then
        log_error "This script requires macOS"
        ((errors++))
    fi

    # Check required commands exist
    local required_commands=("curl" "git" "xcode-select")
    for cmd in "${required_commands[@]}"; do
        if ! command -v "$cmd" >/dev/null 2>&1; then
            log_error "Required command not found: $cmd"
            ((errors++))
        fi
    done

    # Check available disk space
    local available_space
    available_space=$(df -h "$HOME" | awk 'NR==2 {print $4}' | sed 's/G//')
    if [[ "${available_space%.*}" -lt 1 ]]; then
        log_error "Insufficient disk space (need at least 1GB)"
        ((errors++))
    fi

    return $errors
}

The command -v pattern is the most reliable way to check whether a command exists on the system. Unlike which, it works correctly in all shells and does not produce unwanted output. The error counter pattern allows all checks to run so the user sees every issue at once, rather than fixing them one at a time.

Retry Logic with Exponential Backoff

Network operations are inherently unreliable. A server might be temporarily overloaded, a DNS lookup might time out, or a connection might be briefly interrupted. Rather than failing immediately, professional scripts retry the operation with increasing delays between attempts. This pattern is called exponential backoff because the delay doubles with each retry.

retry_with_backoff() {
    local max_attempts="${MAX_RETRIES:-3}"
    local delay="${RETRY_DELAY:-5}"
    local attempt=1

    while [[ $attempt -le $max_attempts ]]; do
        if "$@"; then
            return 0
        fi

        if [[ $attempt -lt $max_attempts ]]; then
            log_warning "Attempt $attempt failed, retrying in ${delay}s..."
            sleep "$delay"
            delay=$((delay * 2))  # Double the delay each time
        fi

        ((attempt++))
    done

    log_error "All $max_attempts attempts failed for: $*"
    return 1
}

The "$@" variable expands to all arguments passed to the function, preserving quoting. This means you can pass any command and its arguments to retry_with_backoff and it will retry that exact command. For example: retry_with_backoff brew install visual-studio-code. The increasing delay prevents overwhelming a recovering service and gives transient issues time to resolve.

6. Logging and Debugging

A good logging system is your best friend when something goes wrong. It provides a complete record of what happened, when it happened, and in what order. The Brew Scripts logging system writes to both the console (with colors for readability) and a file (with timestamps for debugging), and supports multiple severity levels so you can filter for the information you need.

Structured Logging System

The logging system uses numeric severity levels to control which messages are displayed. In normal operation, you might only see INFO and above. During debugging, you can lower the threshold to see DEBUG messages that provide detailed information about every operation.

# Define log levels with numeric values for comparison
readonly LOG_LEVEL_DEBUG=0
readonly LOG_LEVEL_INFO=1
readonly LOG_LEVEL_WARNING=2
readonly LOG_LEVEL_ERROR=3

log_message() {
    local level="$1"
    local level_num="$2"
    local color="$3"
    local message="$4"

    # Check if this message meets the current log level threshold
    local current_level_num
    current_level_num=$(get_log_level_num)
    if [[ $level_num -lt $current_level_num ]]; then
        return 0
    fi

    local timestamp
    timestamp=$(date '+%Y-%m-%d %H:%M:%S')

    # Console output with color for readability
    echo -e "${color}[$level]${NC} $message"

    # File output without color codes for clean log files
    if [[ -n "${LOG_FILE:-}" ]]; then
        echo "[$timestamp] [$level] $message" >> "$LOG_FILE"
    fi
}

# Convenience wrappers for each log level
log_debug()   { log_message "DEBUG"   $LOG_LEVEL_DEBUG   "$BLUE"   "$1"; }
log_info()    { log_message "INFO"    $LOG_LEVEL_INFO    "$NC"     "$1"; }
log_warning() { log_message "WARNING" $LOG_LEVEL_WARNING "$YELLOW" "$1"; }
log_error()   { log_message "ERROR"   $LOG_LEVEL_ERROR   "$RED"    "$1"; }
log_success() { log_message "SUCCESS" $LOG_LEVEL_INFO    "$GREEN"  "$1"; }

The dual-output design is intentional. Console output uses colors because they are easy to scan visually. File output strips colors (which would appear as garbage escape sequences in a text file) and adds timestamps, which are essential for understanding the sequence and timing of operations when reviewing logs after the fact.

Debug Mode

Debug mode provides maximum visibility into what a script is doing. It is activated by passing the --debug flag and enables Bash's command tracing feature, which prints every command before it executes.

# Enable debug mode when the --debug flag is passed
if [[ "${DEBUG_MODE:-false}" == "true" ]]; then
    set -x          # Print every command before execution
    LOG_LEVEL="DEBUG"  # Show all log messages including debug level
fi

The set -x flag is incredibly powerful for troubleshooting. It shows you the exact command being executed after all variable expansion, quoting, and globbing have been applied. This is often the fastest way to find out why a command is not doing what you expect — you can see exactly what arguments it is receiving.

7. System Detection and Adaptation

macOS runs on two different processor architectures (Intel x86_64 and Apple Silicon arm64), and Homebrew installs to different directories depending on which architecture is in use. Scripts that need to work on both platforms must detect the architecture at runtime and adapt their behavior accordingly. This section shows how to write portable scripts that work correctly on any Mac.

Architecture Detection

The uname -m command returns the machine's hardware architecture. By wrapping this in a function, you create a clean abstraction that the rest of your script can use without needing to know the details of how architecture detection works.

detect_architecture() {
    local arch
    arch="$(uname -m)"

    case "$arch" in
        "arm64")
            echo "apple_silicon"
            ;;
        "x86_64")
            echo "intel"
            ;;
        *)
            echo "unknown"
            ;;
    esac
}

get_homebrew_prefix() {
    local arch
    arch=$(detect_architecture)

    case "$arch" in
        "apple_silicon")
            echo "/opt/homebrew"
            ;;
        "intel")
            echo "/usr/local"
            ;;
        *)
            log_error "Unknown architecture: $arch"
            return 1
            ;;
    esac
}

This is a real-world example of the adapter pattern. On Apple Silicon Macs, Homebrew installs to /opt/homebrew, while on Intel Macs it installs to /usr/local. By encapsulating this logic in a function, every other part of the script can simply call get_homebrew_prefix and get the correct path without worrying about which architecture it is running on.

Power and Network Awareness

Automated tasks that run in the background should be aware of system conditions. You probably do not want a large update to start downloading packages when your laptop is on battery power or connected to a tethered phone connection. The following functions check these conditions before proceeding.

check_power_status() {
    local power_info
    power_info=$(pmset -g ps 2>/dev/null)

    if [[ "${REQUIRE_AC_POWER:-true}" == "true" ]]; then
        if echo "$power_info" | grep -q "AC Power"; then
            log_success "Device is connected to AC power"
            return 0
        else
            log_warning "Device is running on battery power"
            return 1
        fi
    fi

    return 0  # AC power not required, always pass
}

check_network() {
    local target_network="${WIFI_NETWORK:-}"

    # If no specific network is required, just check for connectivity
    if [[ -z "$target_network" ]]; then
        if curl -s --max-time 5 -o /dev/null https://github.com; then
            log_success "Network connectivity confirmed"
            return 0
        else
            log_error "No network connectivity"
            return 1
        fi
    fi

    # Check if connected to the specified network
    local current_network
    current_network=$(/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport -I | awk '/ SSID/ {print $2}')

    if [[ "$current_network" == "$target_network" ]]; then
        log_success "Connected to required network: $target_network"
        return 0
    else
        log_warning "Not connected to required network ($target_network), currently on: $current_network"
        return 1
    fi
}

These environmental awareness functions demonstrate an important principle: scripts that run unattended need to be smarter about when and how they operate. By checking power and network status before starting, the auto-update scripts avoid draining your battery or consuming metered data. The configuration variables (REQUIRE_AC_POWER and WIFI_NETWORK) let users control this behavior through the config file.

8. Practical Exercises

The best way to learn shell scripting is to write shell scripts. These exercises are designed to reinforce the concepts covered in this guide. Each exercise builds on the patterns you have seen in the Brew Scripts source code. Try to complete them on your own before looking at the hints, and test your solutions using bash -n for syntax checking and shellcheck for best practice analysis.

Exercise 1: Directory Management

Write a function called ensure_directory that takes a directory path as an argument. If the directory exists, it should log a success message and return. If it does not exist, it should create it (including any parent directories) and log what it did. The function should handle errors such as permission denied and return appropriate exit codes.

ensure_directory() {
    local dir_path="$1"

    # Your implementation here:
    # 1. Validate that dir_path is not empty
    # 2. Check if the directory already exists
    # 3. If not, create it with mkdir -p
    # 4. Handle errors and log the result
}

Exercise 2: Configuration Validation

Create a function called validate_config_file that takes a file path and verifies that the file exists, is readable, and is not empty. It should return 0 if the config file is valid and 1 otherwise, logging specific error messages for each failure mode so the user knows exactly what is wrong.

validate_config_file() {
    local config_path="$1"

    # Your implementation here:
    # 1. Check if the file exists (-f test)
    # 2. Check if the file is readable (-r test)
    # 3. Check if the file is non-empty (-s test)
    # 4. Log specific errors for each failure case
    # 5. Return 0 if all checks pass, 1 otherwise
}

Exercise 3: Interactive Choice Menu

Build a function called show_menu that presents a numbered list of options to the user and returns their selection. The function should accept an array of option strings, display them with numbers, validate that the user's input is a valid number within range, and loop until a valid choice is made.

show_menu() {
    local title="$1"
    shift
    local options=("$@")

    # Your implementation here:
    # 1. Print the title
    # 2. Print each option with a number
    # 3. Prompt for a choice
    # 4. Validate the input is a number in range
    # 5. Echo the selected option text
    # 6. Loop until valid input is received
}

9. Next Steps and Resources

This guide has covered the core patterns used in professional shell scripting: strict error handling, structured configuration, modular functions, interactive user input, defensive programming, structured logging, and system-aware automation. These are the same patterns used in production environments at companies of all sizes.

To continue your learning journey, here are the recommended next steps:

1. Study the actual scripts in the Brew Scripts repository. Now that you understand the patterns, reading the full source code will reinforce your knowledge and show you how the pieces fit together in a complete application.
2. Modify the configuration and observe how changes affect script behavior. Experimenting with the config file is a safe, low-risk way to learn how configuration-driven scripts work.
3. Add your own functions to extend the scripts. Start with small additions and use the existing functions as templates for your code's style and structure.
4. Create your own scripts using the patterns from this guide. The best way to internalize these techniques is to use them to solve your own problems.
5. Share your improvements with the community. If you build something useful, consider opening a pull request or sharing it with other learners.

Recommended Resources

These external resources complement this guide and provide deeper dives into specific topics:

• Bash Reference Manual — The official Bash documentation. Comprehensive and authoritative, this is the definitive reference for every Bash feature and syntax detail.
• ShellCheck — A static analysis tool for shell scripts. Paste your script into the web interface or install it locally, and it will identify bugs, portability issues, and style problems with detailed explanations.
• Google Shell Style Guide — Google's internal guidelines for writing shell scripts. Even if you do not follow every recommendation, it provides a well-reasoned framework for consistent, readable shell code.
• Advanced Bash-Scripting Guide — A comprehensive, freely available guide that covers advanced topics like process substitution, signal handling, and regular expressions in Bash.