Bash Script Assembly

Bash script assembly is the practice of structuring, composing, and packaging Bash scripts into reliable, reusable, and maintainable units. It matters when scripts grow beyond simple one-offs—when they orchestrate deployments, process data pipelines, automate infrastructure, or serve as the core logic in CI/CD workflows. Assembly is not just writing a script; it is the deliberate construction of a script’s lifecycle: how it is built, tested, versioned, and deployed, with consistent error handling, logging, configuration, and integration with system tools.

Structuring for Reusability

A well-assembled script begins with a consistent structure that makes it easy to navigate, extend, and debug. The standard layout uses a modular approach with a fixed entry point (main), function definitions, and initialization.

#!/usr/bin/env bash

# Description: Process CSV files and upload results to S3.

set -euo pipefail

# Default configuration
: "${LOG_LEVEL:=info}"
: "${S3_BUCKET:=my-data-bucket}"
: "${TEMP_DIR:=/tmp}"

# Global variables
declare -r SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
declare -r LOG_FILE="/var/log/my-script.log"

# Functions
log() {
  local level="$1"
  local message="$2"
  local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
  echo "[$timestamp] [$level] $message" | tee -a "$LOG_FILE"
}

error() {
  local message="$1"
  log "ERROR" "$message"
  exit 1
}

setup() {
  # Ensure required tools are installed
  for cmd in jq aws curl; do
    if ! command -v "$cmd" &>/dev/null; then
    error "Missing required command: $cmd"
    fi
  done

  # Create temp directory if it doesn't exist
  if [[ ! -d "$TEMP_DIR" ]]; then
    mkdir -p "$TEMP_DIR" || error "Failed to create temp directory: $TEMP_DIR"
  fi
}

process_csv() {
  local file="$1"
  local output_dir="$2"

  log "INFO" "Processing $file"

  # Validate input
  if [[ ! -f "$file" ]]; then
    error "Input file not found: $file"
  fi

  # Transform and output
  jq -r '.[] | [.name, .value] | @csv' "$file" \
    | sed 's/^"//;s/"$//;s/","/|/g' \
    > "$output_dir/result.txt"

  log "INFO" "Completed processing: $file"
}

main() {
  local input_file="$1"
  local output_dir="$2"

  setup
  process_csv "$input_file" "$output_dir"
  log "INFO" "Script completed successfully"
}

# Parse arguments
case "$#" in
  2)
    main "$1" "$2"
    ;;
  0)
    error "Usage: $0 <input.csv> <output-dir>"
    ;;
  *)
    error "Expected 2 arguments; got $#: $*"
    ;;
esac

This structure enables reuse across projects. The set -euo pipefail ensures robustness: -e exits on any error, -u flags undefined variables, -o pipefail propagates failure across pipelines. The : "${VAR:=default}" idiom sets defaults from environment variables, which is critical for deployment flexibility.

Composing Scripts with Dependencies

Assembly becomes meaningful when scripts depend on each other. The key is to define a clear interface: input arguments, exit codes, and error output.

A common pattern is to use a bin/ directory containing executable scripts, each with a consistent signature.

# bin/deploy.sh
#!/usr/bin/env bash
set -euo pipefail

main() {
  local target_env="$1"
  local app_version="$2"

  case "$target_env" in
    production)
      export AWS_PROFILE=prod
      ;;
    staging)
      export AWS_PROFILE=staging
      ;;
    *)
      error "Unknown environment: $target_env"
      ;;
  esac

  # Run multiple scripts in sequence
  bin/build.sh "$app_version" || error "Build failed"
  bin/test.sh || error "Tests failed"
  bin/rollout.sh "$target_env" "$app_version" || error "Rollout failed"

  log "INFO" "Deployment to $target_env completed"
}

main "$@"

Each dependent script exports a standard error message format. A failure in bin/build.sh produces:

Build failed
Error: Failed to compile assets

The main script in deploy.sh captures this and exits with code 1, which triggers CI/CD tooling or orchestration.

The critical edge: order matters in argument parsing. If deploy.sh uses "$@" but build.sh expects two arguments ($1, $2), and deploy.sh calls it with bin/build.sh "$version", then "$@" in deploy.sh passes "$version" as a single argument, not two. The fix is explicit:

bin/build.sh "$app_version" "$app_version"

Versioning and Configuration

Assembly requires consistent versioning and configuration. The most common approach is to use a config.sh file loaded at script startup.

# config.sh
export APP_NAME="MyApp"
export LOG_LEVEL="debug"
export MAX_RETRIES=5
export API_ENDPOINT="https://api.example.com/v1"
export CACHE_DIR="/var/cache/app"

The main script loads it:

# main.sh
source "$SCRIPT_DIR/config.sh"

This file may be versioned independently. A deployment might use:

# deploy.sh
export CONFIG_FILE="/opt/app/config.prod.sh"
source "$CONFIG_FILE"

The file path can be overridden via environment variable or argument.

A silent failure: if config.sh is not found, the script proceeds with defaults, but no error is logged. To catch this:

if [[ ! -f "$CONFIG_FILE" ]]; then
  log "WARNING" "Configuration file not found: $CONFIG_FILE"
else
  source "$CONFIG_FILE"
fi

Another edge: variable expansion in config files. If config.sh contains:

export LOG_DIR="$CACHE_DIR/logs"

and CACHE_DIR is set earlier, it is not expanded unless source is used. If the config file is sourced with source "$CONFIG_FILE", the expansion happens; if source is omitted, $CACHE_DIR is literal.

Error Handling and Logging

Robust assembly relies on structured error reporting. The error() function in the example above logs to a file and exits. But errors may be silent.

The common failure: uncaught command failures. A script runs aws s3 cp, but the command fails silently due to incorrect permissions, and the script proceeds.

To fix, use set -e and pipefail, but also wrap commands in if blocks or || clauses.

if ! aws s3 cp "$LOCAL_FILE" "s3://$BUCKET/$REMOTE_PATH"; then
  log "ERROR" "S3 upload failed for $LOCAL_FILE"
  exit 1
fi

Better: use a try-catch pattern with set -E and trap.

set -euo pipefail
set -E  # Enable ERR trap on function calls

error_handler() {
  local exit_code="$?"
  local line_number="$1"
  local script_name="$2"
  log "ERROR" "Script $script_name failed at line $line_number with exit code $exit_code"
  exit "$exit_code"
}

trap 'error_handler $LINENO $0' ERR

# Now, any command failure triggers the trap
aws s3 sync . s3://my-bucket/

The trap is especially useful in multi-stage scripts where a single failure in a chain of commands needs to be reported clearly.

Testing and Validation

Assembly includes testing. A script should be testable in isolation.

A common test setup uses shunit2, but the minimal approach uses a test/ directory with shell scripts.

# test/test-build.sh
#!/usr/bin/env bash
set -euo pipefail

# Load test library
source shunit2

test_build_success() {
  local temp_dir=$(mktemp -d)
  local input_file="$temp_dir/data.csv"
  local output_dir="$temp_dir/output"

  # Create test input
  cat > "$input_file" <<'EOF'
{"name": "Alice", "value": 100}
{"name": "Bob", "value": 200}
EOF

  # Run build
  bin/build.sh "$input_file" "$output_dir"

  # Validate output
  assertTrue "Output directory exists" "[ -d $output_dir ]"
  assertTrue "Output file exists" "[ -f $output_dir/result.txt ]"
  assertEquals "Output content" "Alice|100" "$(head -n1 "$output_dir/result.txt")"
}

# Run tests
. shunit2

The test script uses assertTrue, assertEquals, and . to source the test framework. It assumes shunit2 is installed via apt install shunit2.

A subtle failure: test scripts not being executable. A test/ directory with test-build.sh but no chmod +x test-build.sh leads to sh: test-build.sh: command not found when running sh test-build.sh.

Another edge: test environment setup. The test may need a temporary directory, but the temp_dir is not cleaned up. The fix is to use trap in the test script:

trap 'rm -rf $temp_dir' EXIT

Packaging and Distribution

Assembly culminates in packaging. The script is deployed as a single file, or as a directory with metadata.

A common pattern is to bundle a script with dependencies into a .tar.gz archive.

# build.sh
#!/usr/bin/env bash
set -euo pipefail

export SCRIPT_NAME="app-deployer"
export VERSION="1.2.0"
export OUTPUT_DIR="dist/$SCRIPT_NAME-$VERSION"

mkdir -p "$OUTPUT_DIR"

# Copy script and dependencies
cp -r bin/ "$OUTPUT_DIR/"
cp config.sh "$OUTPUT_DIR/"
cp README.md "$OUTPUT_DIR/"
cp LICENSE "$OUTPUT_DIR/"

# Make script executable
chmod +x "$OUTPUT_DIR/bin/deploy.sh"

# Create archive
tar -czf "$SCRIPT_NAME-$VERSION.tar.gz" -C dist/ "$SCRIPT_NAME-$VERSION"

log "INFO" "Built $SCRIPT_NAME-$VERSION.tar.gz"

The resulting archive contains:

app-deployer-1.2.0.tar.gz
├── app-deployer-1.2.0/
│   ├── bin/
│   │   └── deploy.sh
│   ├── config.sh
│   ├── README.md
│   └── LICENSE

This archive is versioned and deployed via CI/CD. The deployment script extracts it:

tar -xzf app-deployer-1.2.0.tar.gz -C /opt/app/

A silent failure: missing bin/ directory. If bin/deploy.sh is not present, the script fails with:

sh: bin/deploy.sh: command not found

This happens when cp -r bin/ is used but bin is not a directory, or when bin/deploy.sh is in bin/deploy.sh (a file named deploy.sh inside bin).

Orchestration and Execution

Assembly is not complete until the script is orchestrated. The final step is to define a Makefile or a run.sh script that encapsulates execution.

# Makefile
.PHONY: all build test deploy

all: build test

build:
	@echo "Building the application..."
	@./build.sh

test:
	@echo "Running tests..."
	@cd test && ./test-build.sh

deploy:
	@echo "Deploying to production..."
	@./deploy.sh production 1.2.0

A run.sh script may take over:

#!/usr/bin/env bash
# run.sh

set -euo pipefail

export ENVIRONMENT="${ENVIRONMENT:-development}"
export CONFIG_FILE="${CONFIG_FILE:-config.$ENVIRONMENT.sh}"

echo "Starting application in $ENVIRONMENT mode"

source "$CONFIG_FILE"

exec bin/main.sh "$@"

The exec ensures the script replaces the current process, making it easy to manage with systemctl or supervisord.

The critical edge: the script starts but never finishes. If main.sh runs bin/process.sh, and bin/process.sh uses exec, then main.sh exits immediately, and the process is lost. The fix is to use exec in main.sh as well:

exec bin/main.sh "$@"

This ensures the entire orchestration runs as a single process, making monitoring, logging, and restarts effective.

Assembly is complete when every part—structure, composition, configuration, error handling, testing, packaging, and orchestration—works together, with no silent failure, no missing file, no uncaught error. It is the craft of building Bash scripts not as code, but as systems.

This page was rewritten on 11 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.

Join the Newsletter

Get the latest updates and deep insights shipped directly to your inbox.