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'
-eexits when a command returns a non-zero status that is not being tested.-utreats the expansion of an unset variable as an error, catching typos and missing configuration instead of silently substituting an empty string. This is what stopsrm -rf "$PREFIX/data"from becomingrm -rf /data.-o pipefailmakes a pipeline return the status of the last failing stage rather than only the last stage, socurl … | tar -xno longer reports success when the download failed.- Narrowing
IFSto 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.
| Construct | Use 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 $dstbreaks 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, ormapfile. - Piping into a
whileloop. The loop runs in a subshell and its variables vanish. Redirect or use process substitution. - Assuming
cdsucceeded.cd "$dir" && rm -rf ./*is safe; the same on two lines withoutset -eis a disaster. local x=$(cmd)underset -e. The failure is hidden. Declare and assign separately.- Building file paths without a trailing check.
rm -rf "$root/$name"with an empty$nameremoves the whole tree.set -uplus 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 pipefailand a comment saying what it does — then know the cases-ecannot 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; usecasewhen matching one value against several patterns. - Loop over globs and arrays, feed
while readfrom 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 throughreturn. trap … EXITguarantees cleanup on every path, andflockon 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.