Linux Administration

Bash Scripting: Safe Scripts with Arguments, Loops, Functions and Traps

Intermediate9 min readUpdated

A shell script is production code that happens to look like a list of commands, and most of its bugs come from the shell's habit of carrying on after a failure. This guide shows the structure of a script worth trusting: a strict preamble, parsed arguments, tested conditions, functions with real exit codes, cleanup handled by a trap, and a linter in the loop. It ends with a complete, annotated backup script.

What you will learn

  • Structure a script with a shebang, a strict preamble and clearly separated functions
  • Parse options and positional arguments and validate them before doing any work
  • Choose the correct test construct and write loops that survive spaces and empty lists
  • Guarantee cleanup and useful error messages with trap, ERR and EXIT handlers
  • Lint scripts with ShellCheck and decide when Bash is the wrong tool

The difference between a handful of commands you typed once and a script other people rely on is error handling. Interactive shells are forgiving: a command fails, you see the message and try something else. A script has nobody watching, and by default the shell simply proceeds to the next line — which is how a backup script deletes the previous backup after the new one failed to be created, and how a deployment script restarts a service with a configuration file that was never written.

This guide is about writing the second kind of script deliberately. It assumes you already know the command line — expansion, quoting, redirection, exit status — from shell basics, and focuses on the constructs that turn commands into a program: strict mode, argument handling, control flow, functions, arrays, cleanup traps and linting.

The shape of a script

A script begins with a shebang, the two-character sequence #! followed by the interpreter the kernel should run. #!/usr/bin/env bash finds Bash wherever it lives rather than assuming /bin/bash, which matters on systems where it sits under /usr/local. Do not write #!/bin/sh unless the script is strictly POSIX — on Debian and Ubuntu /bin/sh is Dash, which has no arrays, no [[, no local -n and different echo behaviour.

#!/usr/bin/env bash
#
# deploy.sh — install a release into /opt and switch the current symlink.
# Usage: deploy.sh [-n] [-d DIR] VERSION

Make it executable with chmod +x deploy.sh and run it as ./deploy.sh. Running bash deploy.sh ignores the shebang entirely, which is exactly how a Bash script ends up being interpreted by Dash in a CI job and failing on a construct that works everywhere else.

Put a comment block at the top saying what the script does and how it is called. Six months later that block is the documentation.

The strict preamble

Three shell options, set together, change the default from "carry on regardless" to "stop at the first sign of trouble".

set -euo pipefail
IFS=$'\n\t'
  • -e exits when a command returns a non-zero status that is not being tested.
  • -u treats the expansion of an unset variable as an error, catching typos and missing configuration instead of silently substituting an empty string. This is what stops rm -rf "$PREFIX/data" from becoming rm -rf /data.
  • -o pipefail makes a pipeline return the status of the last failing stage rather than only the last stage, so curl … | tar -x no longer reports success when the download failed.
  • Narrowing IFS to newline and tab removes the space from the word-splitting character set, reducing the damage an unquoted expansion can do. It is optional and changes the behaviour of some idioms, so adopt it consciously.

Be aware of what -e does not catch. A command inside if, while, && or ! is being tested, so its failure is expected and does not exit. local var=$(cmd) masks the status of cmd behind the always-successful local, so split it:

local sha
sha=$(sha256sum "$file" | cut -d' ' -f1)   # now a failure here stops the script

Where a command is genuinely allowed to fail, say so explicitly with || true so the intent is visible, and where you want the status without exiting, capture it:

grep -q "^enabled=1" "$conf" || echo "warning: feature disabled"
if ! systemctl is-active --quiet nginx; then
  echo "nginx is not running" >&2
fi

Arguments and options

Positional parameters are $1, $2 and so on; $# is the count, "$@" expands to all of them as separate quoted words, and $0 is the script's own name. "$@" with the quotes is one of the few things in Bash that is almost never wrong — $* joins everything into a single string and is almost never right.

For anything beyond one or two arguments, parse options with getopts. It handles short options, bundling and option arguments, and it is a builtin, so there is nothing to install.

usage() {
  cat >&2 <<'USAGE'
Usage: deploy.sh [-n] [-d DIR] VERSION
  -n        dry run: print what would happen, change nothing
  -d DIR    installation root (default /opt)
USAGE
  exit 64
}

dry_run=false
root=/opt

while getopts ':nd:h' opt; do
  case "$opt" in
    n) dry_run=true ;;
    d) root=$OPTARG ;;
    h) usage ;;
    :) printf 'option -%s requires an argument\n' "$OPTARG" >&2; usage ;;
    ?) printf 'unknown option -%s\n' "$OPTARG" >&2; usage ;;
  esac
done
shift $((OPTIND - 1))

[[ $# -eq 1 ]] || usage
version=$1

The leading colon in ':nd:h' switches getopts into silent error mode so your own messages are used; a colon after a letter means that option takes a value. shift $((OPTIND - 1)) removes the parsed options, leaving the positional arguments in place.

Validate everything before doing anything destructive. A script that checks its inputs at the top and then runs is far easier to reason about than one that discovers a missing directory halfway through.

[[ -d $root ]]            || { printf 'no such directory: %s\n' "$root" >&2; exit 66; }
[[ $version =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { printf 'bad version: %s\n' "$version" >&2; exit 65; }
command -v rsync >/dev/null || { echo 'rsync is required' >&2; exit 69; }

Exit with 0 on success and a distinct non-zero code per failure class; the conventional values in /usr/include/sysexits.h (64 usage, 65 data, 66 no input, 69 unavailable) are a reasonable convention when you need more than "it broke". Whatever you choose, send diagnostics to standard error with >&2 so that a caller piping your output gets only the output.

Conditions

Bash offers three test constructs and the differences matter.

ConstructUse it for
[[ … ]]everything, in Bash: no word splitting inside, supports =~, &&, ||, pattern matching with ==
[ … ]POSIX scripts only; every expansion must be quoted
(( … ))integer arithmetic: (( count > 3 )), (( i++ ))
[[ -f $config ]]            # exists and is a regular file
[[ -d $dir && -w $dir ]]    # directory, writable
[[ -s $log ]]               # exists and is non-empty
[[ -z ${API_TOKEN:-} ]]     # unset or empty, safe under set -u
[[ $name == web-* ]]        # glob match
[[ $line =~ ^([0-9]{3})\ (.*)$ ]] && code=${BASH_REMATCH[1]}
(( retries < max_retries ))

Inside [[ ]] there is no word splitting, so [[ -f $config ]] is safe even when the path contains spaces — one of the few places where omitting the quotes is fine. On the right of == and =~, quoting has the opposite effect: quoted means literal, unquoted means pattern or regex.

case is cleaner than a chain of comparisons when matching a value against several patterns:

case "$environment" in
  prod|production) replicas=6 ;;
  stag*)           replicas=2 ;;
  dev)             replicas=1 ;;
  *) printf 'unknown environment: %s\n' "$environment" >&2; exit 65 ;;
esac

Loops that do not break on spaces

Iterating over a glob or an array is safe; iterating over the output of ls is not.

for file in /var/log/app/*.log; do      # safe; use shopt -s nullglob for empty matches
  gzip -9 -- "$file"
done

for host in "${hosts[@]}"; do
  ssh "$host" 'uptime'
done

for i in {1..5}; do
  curl -fsS "https://api.example.com/health" && break
  sleep $(( i * 2 ))                    # simple exponential backoff
done

Reading a file line by line has one correct form, and every part of it is load-bearing:

while IFS= read -r line; do
  printf 'got: %s\n' "$line"
done < "$input_file"

IFS= prevents leading and trailing whitespace being stripped, -r stops backslashes being interpreted as escapes, and the redirection at the done keeps the loop in the current shell. That last point is the subject of one of the most common Bash bugs: piping into a loop (cat file | while read …) runs the loop in a subshell, so any variable it sets is gone afterwards. Use a redirection, or process substitution when the input is a command:

count=0
while IFS= read -r unit; do
  (( count++ ))
done < <(systemctl list-units --type=service --state=failed --no-legend | awk '{print $1}')
printf 'failed units: %d\n' "$count"

For file names that may contain anything at all, pair find -print0 with read -d '':

while IFS= read -r -d '' path; do
  rm -v -- "$path"
done < <(find /tmp/build -type f -name '*.tmp' -print0)

Functions

A function groups steps, gives them a name and lets you test them in isolation. Arguments arrive as $1, $2, "$@" exactly as in the script itself; return sets an exit status, and output written to stdout is how a function returns a value.

log() { printf '%s [%s] %s\n' "$(date -Is)" "$1" "${*:2}" >&2; }

require_service() {
  local unit=$1
  if ! systemctl is-active --quiet "$unit"; then
    log ERROR "$unit is not running"
    return 1
  fi
}

current_release() {
  readlink -f /opt/app | sed 's|.*/||'
}

release=$(current_release)
require_service postgresql || exit 69

Declare every internal variable local, otherwise it is global and two functions eventually collide. Send log lines to standard error, as log does above, so that a function whose stdout is captured by command substitution is not polluted by its own logging — a subtle bug that produces bizarre values in the caller.

return only accepts values between 0 and 255, so a function cannot return a number, a string or a list that way. Print it and capture it.

Arrays

Arrays are the reason to insist on Bash rather than POSIX sh. They keep a list of values with their boundaries intact, which strings cannot do.

rsync_opts=(--archive --delete --human-readable)
[[ $dry_run == true ]] && rsync_opts+=(--dry-run)
rsync "${rsync_opts[@]}" "$src/" "$dest/"

hosts=(web01 web02 db01)
printf 'host count: %d\n' "${#hosts[@]}"
printf '%s\n' "${hosts[@]}"

mapfile -t failed < <(systemctl list-units --state=failed --no-legend | awk '{print $1}')

"${array[@]}" with the quotes expands to one word per element, preserving spaces; ${array[*]} joins into one string. mapfile -t (also spelled readarray) reads lines into an array without the trailing newlines and is far safer than arr=$(cmd) followed by word splitting.

Associative arrays act as a small key-value store and must be declared:

declare -A port_of=( [http]=80 [https]=443 [postgres]=5432 )
for name in "${!port_of[@]}"; do
  printf '%-10s %s\n' "$name" "${port_of[$name]}"
done

Here-documents and generated files

A here-document feeds a block of literal text to a command's standard input. Quoting the delimiter decides whether the body is expanded:

cat > /etc/myapp/config.ini <<EOF
[server]
host = ${bind_address}
port = ${port}
EOF

sudo tee /etc/systemd/system/myapp.service > /dev/null <<'UNIT'
[Unit]
Description=My application
UNIT

<<'EOF' with quotes is literal — nothing inside is expanded, which is what you want when generating a script or a config full of $ signs. <<EOF unquoted expands variables and command substitutions. <<-EOF additionally strips leading tabs (not spaces), allowing the body to be indented with the surrounding code.

Never write a configuration file in place with a redirection while a service is reading it. Write to a temporary file in the same directory and mv it into position: mv within one filesystem is atomic, so readers see either the old file or the new one and never a half-written one.

Cleanup with traps

A trap runs a command when the shell receives a signal or is about to exit. It is how a script cleans up after itself whether it succeeded, failed or was interrupted.

workdir=$(mktemp -d)
cleanup() {
  local status=$?
  rm -rf -- "$workdir"
  (( status == 0 )) || log ERROR "failed with status $status at line $BASH_LINENO"
  exit "$status"
}
trap cleanup EXIT
trap 'log WARN "interrupted"; exit 130' INT TERM

EXIT fires on every exit path, which makes it the right place for removing temporary directories, releasing a lock or restoring a configuration file. Capture $? as the first statement in the handler, before anything else overwrites it.

A companion pattern prevents two copies of a periodic script running at once:

exec 9> /var/lock/backup.lock
flock -n 9 || { echo 'another run is in progress' >&2; exit 75; }

The lock is held by the file descriptor and released automatically when the process ends, including if it is killed — no stale lock file to clean up. flock is also available as a command wrapper, which is handy in a timer unit: flock -n /var/lock/backup.lock /usr/local/bin/backup.sh.

A worked example

The pieces together, as a script you could schedule from a systemd timer:

#!/usr/bin/env bash
#
# backup-db.sh — dump a PostgreSQL database, compress it, upload it and prune old copies.
set -euo pipefail

readonly DB=${DB:-orders}
readonly DEST=${DEST:-/srv/backups}
readonly KEEP_DAYS=${KEEP_DAYS:-14}
readonly STAMP=$(date +%Y%m%dT%H%M%S)

log() { printf '%s %s\n' "$(date -Is)" "$*" >&2; }

workdir=$(mktemp -d)
trap 'rc=$?; rm -rf -- "$workdir"; exit "$rc"' EXIT

exec 9> /var/lock/backup-db.lock
flock -n 9 || { log 'another backup is running'; exit 75; }

for tool in pg_dump zstd sha256sum; do
  command -v "$tool" >/dev/null || { log "missing required tool: $tool"; exit 69; }
done

dump=$workdir/$DB-$STAMP.sql.zst
log "dumping $DB"
pg_dump --format=plain --no-owner "$DB" | zstd -T0 -19 -o "$dump" -q

# Guard against an empty or truncated dump before anything is pruned.
size=$(stat -c %s "$dump")
(( size > 1024 )) || { log "dump is only $size bytes; aborting"; exit 65; }

sha256sum "$dump" > "$dump.sha256"
install -d -m 0750 "$DEST"
mv -- "$dump" "$dump.sha256" "$DEST/"
log "stored $DEST/$(basename "$dump") ($size bytes)"

# Only prune once the new backup is safely in place.
deleted=0
while IFS= read -r -d '' old; do
  rm -f -- "$old" "$old.sha256"
  (( ++deleted ))
done < <(find "$DEST" -maxdepth 1 -name "$DB-*.sql.zst" -mtime "+$KEEP_DAYS" -print0)
log "pruned $deleted old backup(s)"

Notice the ordering: verify the tools, take the lock, produce the new artefact, check it is plausible, move it into place atomically, and only then delete anything old. A script that prunes first and dumps second will eventually leave you with no backups at all.

Linting, testing and formatting

ShellCheck is the single highest-value tool in shell development. It statically analyses a script and reports unquoted expansions, useless cat, subshell variable loss, misuse of [ and dozens of other real bugs, each with a wiki page explaining the reasoning.

sudo apt install shellcheck        # or: dnf install ShellCheck
shellcheck -x -S style deploy.sh   # -x follows sourced files
shfmt -i 2 -ci -w deploy.sh        # consistent formatting
bash -n deploy.sh                  # syntax check without executing
bash -x deploy.sh 1.2.3            # trace every command as it runs

Run ShellCheck in CI alongside your other checks — it fits naturally into the pipelines described in continuous delivery. Where a warning is genuinely wrong, silence that one instance with a # shellcheck disable=SC2086 comment and a note explaining why, rather than turning the check off globally.

For behaviour, bats gives you a small test framework, but a great deal is achieved simply by writing functions that take arguments and print results, then calling them from a test script. Add set -x temporarily, or PS4='+ ${BASH_SOURCE}:${LINENO}: ' before it, to get traces that show file and line.

Common mistakes

  • Unquoted expansions. cp $src $dst breaks on the first path with a space. Quote everything; let ShellCheck find the ones you miss.
  • Parsing ls. Its output is for humans. Use a glob, find -print0, or mapfile.
  • Piping into a while loop. The loop runs in a subshell and its variables vanish. Redirect or use process substitution.
  • Assuming cd succeeded. cd "$dir" && rm -rf ./* is safe; the same on two lines without set -e is a disaster.
  • local x=$(cmd) under set -e. The failure is hidden. Declare and assign separately.
  • Building file paths without a trailing check. rm -rf "$root/$name" with an empty $name removes the whole tree. set -u plus explicit validation prevents it.
  • Writing 800 lines of Bash. At that size the language is fighting you; move to Python, Go or a configuration-management tool.

Key takeaways

  • Start every script with #!/usr/bin/env bash, set -euo pipefail and a comment saying what it does — then know the cases -e cannot catch.
  • Parse options with getopts, validate all inputs up front, write diagnostics to stderr and exit with meaningful codes.
  • Prefer [[ … ]] for tests and (( … )) for arithmetic; use case when matching one value against several patterns.
  • Loop over globs and arrays, feed while read from a redirection or process substitution, and use -print0/read -d '' for arbitrary file names.
  • Keep function variables local, log to stderr, and return values by printing them rather than through return.
  • trap … EXIT guarantees cleanup on every path, and flock on a file descriptor prevents overlapping runs without stale lock files.
  • Order destructive operations last: create, verify, move into place atomically, then prune.
  • Run ShellCheck on every script and treat its findings as build failures, not suggestions.

Sources and further reading

Frequently asked questions

Does set -e make my script safe?
It helps, but it has documented blind spots. A failing command inside a condition, on the left of an ampersand pair, or in a function called from an if statement does not trigger an exit. Command substitution in an assignment masks the status unless you declare and assign on separate lines. Treat the strict preamble as a safety net over careful error handling, not as a substitute for it.
Why does my while loop lose the variables it set?
Every stage of a pipeline runs in a subshell, so a loop on the right of a pipe modifies a copy of the environment that vanishes when the pipeline ends. Feed the loop from a redirection or a process substitution instead — done < file, or done < <(command) — and the loop runs in the current shell where the assignments survive. Bash also offers shopt -s lastpipe for non-interactive shells.
When should I stop using Bash and switch to Python?
Bash is excellent at running programs and wiring their input and output together. It is poor at data structures, arithmetic, string manipulation, error handling across many steps and anything needing tests. Once a script passes a few hundred lines, needs nested data, parses JSON or XML seriously, or must be unit tested, a real programming language will be shorter and far easier to maintain.
How do I handle file names containing spaces or newlines?
Quote every expansion, use arrays rather than space-separated strings, and never parse the output of ls. For find, use -print0 with xargs -0, or -exec cmd {} + which passes arguments directly with no shell involved. When reading a list line by line, use IFS= read -r -d '' with null-separated input so that even a newline inside a name is handled correctly.