4.1.1 Script structure

Overview

In advanced shell scripting, structure is what separates quick one‑liners from reliable tools. A well structured script is easier to read, debug, extend, and hand over to someone else. In this chapter, the focus is on how to organize a script from top to bottom, not on the basics of variables, conditionals, or loops which are covered in their own chapters.

You will see a common “skeleton” for serious Bash scripts, understand why each part exists, and learn conventions that experienced shell programmers follow.

Shebang and Interpreter Choice

Every shell script that is intended to be run as a standalone program should start with a shebang line. The shebang tells the operating system which interpreter to use when the script is executed as a program.

A typical modern choice is:

#!/usr/bin/env bash

This form uses the env command to locate bash in the user’s PATH. It is portable across systems where Bash might not live in the same path. Another common but less flexible style is:

#!/bin/bash

Using /bin/sh suggests that the script only uses POSIX shell features and avoids Bash specific syntax. In advanced scripting, you should be explicit. If you use Bash features, say so in the shebang and write for Bash.

The shebang must be the first line of the file with no leading spaces and no blank lines before it.

File Header and Metadata

Immediately after the shebang, it is good practice to include a header comment that records basic metadata about the script. While not required by the shell, this improves maintainability.

A typical header might contain:

The script name and a one line description.

Author and contact information, if relevant.

Creation date and, optionally, a revision history.

A brief usage summary and key options.

An example header could look like this:

#!/usr/bin/env bash
# backup-home.sh - Simple home directory backup tool
# Author: Jane Doe <jane@example.com>
# Created: 2024-10-01
# Description: Creates compressed backups of the current user's home directory.
# Usage: backup-home.sh [-c] [-d DESTDIR]
#        -c    use checksum verification
#        -d    destination directory for the backup

Keep these comments concise. The goal is to make the script self documenting enough that someone can quickly understand what it is for and how to invoke it.

Enforcing Shell Options

After the header, advanced Bash scripts commonly enable a set of shell options that enforce stricter behavior and reduce subtle bugs. These options influence how the shell reacts to errors and unset variables, and how pipelines behave.

A widely used combination for robust scripts is:

set -Eeuo pipefail

Which combines several single letter options:

-e stops the script when a command fails with a nonzero exit status, with some caveats.

-u treats the use of unset variables as an error.

-o pipefail makes a pipeline fail if any component fails, not just the last one.

-E preserves ERR traps in functions and subshells, which is useful for advanced error handling.

You might also see additional options, such as:

shopt -s nullglob

which affects how globbing behaves when no files match.

Adjustments to set options can be localized later in the script, but the initial configuration belongs near the top to establish predictable behavior.

Global Constants and Configuration

A clear script structure separates configuration and constant values from the core logic. Immediately after shell options, define constants, read configuration, and set default values.

Common elements include:

Default paths, filenames, and directories.

Version numbers and human readable program names.

Exit codes for specific failure conditions.

Environment dependent settings.

For example:

# Global constants
readonly SCRIPT_NAME=${0##*/}
readonly SCRIPT_VERSION="1.2.0"
BACKUP_DIR=${BACKUP_DIR:-/var/backups}
LOG_FILE=${LOG_FILE:-/var/log/backup-home.log}
readonly EXIT_OK=0
readonly EXIT_USAGE=2
readonly EXIT_FAILURE=1

Several structural ideas appear here.

readonly emphasizes that some variables are constants.

Using ${VAR:-default} gives a default that can be overridden by the environment while keeping all defaults in one place.

Named exit codes document the meaning of each nonzero status and avoid scattering magic numbers throughout the script.

If your script reads a configuration file, the logic to locate and load that configuration usually also lives in this section. For example, you might define a default config file path, then source it only if it exists.

Usage and Help Text

A dedicated function that prints usage information and exits is a standard element of well structured scripts. This function is called when the user passes -h or an invalid option, or when required arguments are missing.

A simple usage function might look like this:

print_usage() {
    cat <<EOF
Usage: $SCRIPT_NAME [-c] [-d DESTDIR]
Options:
  -c              use checksum verification
  -d DESTDIR      destination directory for the backup
  -h              show this help message
Version: $SCRIPT_VERSION
EOF
}

Using a here document for multi line help text keeps the structure readable. The usage function should not perform any logic other than printing information. The decision about which usage text to show and with which exit code happens in the argument parsing section.

You might pair print_usage with a print_version function that outputs version information in a consistent format. This is helpful if your script is part of a larger system or is invoked by other tools.

Functions and Modularization

In advanced scripting, the core structural principle is to break logic into functions rather than leaving everything in the top level body. Functions give names to logical units, which improves both readability and testability.

A common ordering is:

Utility functions used across the script.

Error handling functions.

Core action functions that implement the main workflow.

Entry point function, often called main.

Keep functions short and focused. Each function should do one thing and do it well. For example:

log_msg() {
    local level=$1
    shift
    printf '%s [%s] %s\n' "$(date +'%Y-%m-%d %H:%M:%S')" "$level" "$*" \
        >>"$LOG_FILE"
}
die() {
    local exit_code=$1
    shift
    log_msg "ERROR" "$*"
    printf 'Error: %s\n' "$*" >&2
    exit "$exit_code"
}
create_backup() {
    local src_dir=$1
    local dest_dir=$2
    # Actual backup logic here
}

Note how these functions are declared before they are used. While Bash does not require prior declaration in the same way compiled languages do, grouping function declarations in one section makes the script easier to scan.

It is common to place all function definitions together near the top of the file, leaving a short and declarative main section at the bottom.

Argument Parsing Structure

Argument parsing is another structural concern. Even though option parsing itself is covered in more detail elsewhere, the way it is integrated into a script’s top level layout is important.

In a structured script, argument parsing typically happens near the top of the control flow, often inside main. It sets global or main scoped variables that later determine what actions to take.

A customary pattern uses getopts:

parse_args() {
    CHECKSUM=false
    DEST_DIR=$BACKUP_DIR
    while getopts ":cd:h" opt; do
        case "$opt" in
            c)
                CHECKSUM=true
                ;;
            d)
                DEST_DIR=$OPTARG
                ;;
            h)
                print_usage
                exit "$EXIT_OK"
                ;;
            \?)
                printf 'Invalid option: -%s\n' "$OPTARG" >&2
                print_usage
                exit "$EXIT_USAGE"
                ;;
            :)
                printf 'Option -%s requires an argument.\n' "$OPTARG" >&2
                print_usage
                exit "$EXIT_USAGE"
                ;;
        esac
    done
    shift "$((OPTIND - 1))"
    # Remaining positional arguments can be checked here if needed
}

You will notice that parse_args does not perform the script’s main work. It only interprets options, sets variables such as CHECKSUM and DEST_DIR, and enforces minimal correctness. The main workflow functions then act according to these variables.

Placing argument parsing in its own function keeps the top level control flow simple and predictable.

Main Function and Control Flow

A distinctive feature of well structured scripts is the presence of a main function that acts as the central entry point, similar to main in C or other languages. Rather than putting core logic at the top level, advanced scripts wrap it into main and then call main from the bottom of the file.

Here is a typical outline:

main() {
    parse_args "$@"
    log_msg "INFO" "Starting backup to $DEST_DIR"
    if ! create_backup "$HOME" "$DEST_DIR"; then
        die "$EXIT_FAILURE" "Backup failed"
    fi
    log_msg "INFO" "Backup completed successfully"
}
main "$@"

Structurally, this has several advantages.

All high level steps are visible in one place.

You can test supporting functions by sourcing the script without running main, if you guard that call appropriately.

It is easier to control the script’s exit code from a single location.

Sometimes scripts use a guard to detect if they are being sourced or called directly:

if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
    main "$@"
fi

This pattern allows the script to be imported into other scripts as a library of functions without automatically executing the main workflow.

By isolating direct calls to other functions within main, you maintain a clear separation between orchestration and implementation.

Error Handling and Exit Codes

Error handling needs to be designed as part of the script structure from the beginning. A scattered mix of exit 1, unhandled failures, and partial checks leads to fragile scripts. Instead, decide centrally how errors propagate and how exit codes are set.

One effective structural technique is to funnel fatal errors through a single utility function such as die, as shown earlier. This function can log the error, print a user facing message, and terminate with a specific exit code.

Within functions, you have several options.

Return nonzero status and let callers decide whether to turn it into a fatal error.

Use die directly when an error is unrecoverable and very local.

Rely on set -e and set -o pipefail so that unhandled failures abort the script.

For example:

ensure_dir_exists() {
    local dir=$1
    if [[ ! -d "$dir" ]]; then
        die "$EXIT_FAILURE" "Directory does not exist: $dir"
    fi
}
create_backup() {
    local src_dir=$1
    local dest_dir=$2
    ensure_dir_exists "$src_dir"
    ensure_dir_exists "$dest_dir"
    # If this command fails, set -e will cause the script to exit,
    # or the caller can check its status.
    tar -czf "$dest_dir/home-$(date +%Y%m%d).tar.gz" "$src_dir"
}

Documenting the meaning of nonzero exit codes in the header or a dedicated section helps both humans and calling programs understand script behavior.

Logging and Output Structure

The way a script writes text is also part of its structure. Advanced scripts often distinguish between:

Normal user facing output.

Diagnostic output to standard error.

Logging to a file.

Structurally, you can provide helper functions like log_msg, log_error, or debug so that the rest of the script does not need to worry about where to send output or how to format timestamps.

For example:

log_info() {
    log_msg "INFO" "$@"
}
log_error() {
    log_msg "ERROR" "$@"
}
debug() {
    [[ $DEBUG == true ]] || return 0
    log_msg "DEBUG" "$@"
}

Then, the rest of the script calls log_info "something happened" rather than writing directly with echo. This makes it trivial to change formatting or destination later without touching every call site.

You can also structure verbosity control through a global variable like DEBUG or VERBOSE that is set during argument parsing and respected by these helper functions.

By organizing output through centralized helper functions, you keep the top level logic clean and maintain a consistent interface.

Temporary Files and Cleanup

Scripts that create temporary files or acquire resources such as locks should have a defined structural place where cleanup is handled. This is usually done with a dedicated cleanup function and a trap.

A typical pattern looks like:

TMP_DIR=
cleanup() {
    local exit_code=$?
    if [[ -n "$TMP_DIR" && -d "$TMP_DIR" ]]; then
        rm -rf -- "$TMP_DIR"
    fi
    log_msg "INFO" "Exiting with status $exit_code"
}
setup_tmpdir() {
    TMP_DIR=$(mktemp -d) || die "$EXIT_FAILURE" "Failed to create temp directory"
}
trap cleanup EXIT

In this structure:

setup_tmpdir is called early, often from main.

cleanup uses $? to capture the script’s exit code before any other commands change it.

A trap on EXIT ensures cleanup runs when the script terminates normally or due to most noninteractive failures.

Placing the trap and cleanup logic near the top of the script, after global constants and functions, makes the resource management model explicit. It is clear that any part of the script can rely on the existence of TMP_DIR and that it will be removed reliably.

If you need special cleanup on interrupts or termination, you can add specific traps for INT or TERM and delegate to the same cleanup function or to more specialized handlers.

Structuring Scripts as Reusable Modules

Sometimes you want a script to provide both a command line interface and a set of reusable functions that other scripts can source. Structurally, this leads to a pattern where the file contains both library code and a conditional main section.

The key structural component is the check:

if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
    main "$@"
fi

Everything above this check is potentially reusable as a library. Another script can then do:

#!/usr/bin/env bash
# another-script.sh
source "/path/to/backup-home.sh"
main "$@"

or call specific functions from the sourced file. For a reusable module, you may choose to separate the command line interface logic from the core functions even more strictly, by putting argument parsing and main in a separate wrapper script while keeping logic in a pure library script.

This approach encourages you to design functions with clear inputs and outputs and to avoid relying too heavily on global state. It also gives your project a scalable structure as it grows from a single script into a collection of tools.

Putting It All Together

When you combine all the ideas in this chapter, a typical advanced script skeleton looks visually organized and predictable. In outline form, such a script contains:

Shebang and header comments.

Shell options and global configuration.

Utility, logging, and error handling functions.

Core workflow functions.

Argument parsing function.

Optional cleanup and trap setup.

A concise main function that calls the relevant pieces.

A single main "$@" invocation, possibly guarded so the file can act as a module.

By following these structural conventions, you make your scripts more robust and easier to evolve, especially as they grow in size and complexity.