Bash Scripting — Debugging Techniques

Chapter 24 — Debugging Techniques

Welcome to the debugging chapter! 🐛 Every script you write will eventually misbehave — the difference between a frustrated developer and a productive one is knowing how to find the bug quickly. This chapter arms you with every tool in the Bash debugging arsenal.

---

What You’ll Learn

Lesson	Topic	Key Skill
01 — set -x (xtrace)	Execution tracing	Watch every command as it runs
02 — bash -x Flag	Invocation-level debugging	Debug without editing the script
03 — ShellCheck	Static analysis	Catch bugs before you run
04 — Debug Mode	Echo tracing & debug functions	Build your own debug framework
05 — Common Bugs	Bug patterns & fixes	Avoid the top 10 pitfalls
06 — Exercises	Practice	Put it all together

---

Why Debugging Matters

Most scripts fail silently — they don’t crash, they just produce wrong results. Consider this innocent-looking snippet:

#!/usr/bin/env bash
set -euo pipefail

filename=$1
count=$(wc -l < "$filename")
echo "Lines: $count"

Looks fine — until $1 is empty, the file doesn’t exist, or it contains spaces. Debugging tools help you see what Bash actually does versus what you think it does.

---

The Debugging Toolkit at a Glance

┌─────────────────────────────────────────────────┐
│              BASH DEBUGGING TOOLKIT              │
├──────────────┬──────────────────────────────────┤
│  Runtime     │  set -x  ·  bash -x  ·  bash -v │
│  Static      │  ShellCheck  ·  bash -n          │
│  Custom      │  debug()  ·  DEBUG flag          │
│  Defensive   │  set -euo pipefail               │
│  Logging     │  timestamp  ·  FUNCNAME array    │
└──────────────┴──────────────────────────────────┘

---

Debugging Mindset

Before reaching for any tool, follow this mental checklist:

1. Reproduce — Can you trigger the bug consistently?
2. Isolate — Narrow it down to the smallest failing section.
3. Trace — Use set -x or echo to see actual values.
4. Fix — Change one thing at a time.
5. Verify — Confirm the fix and check for regressions.

---

Quick Reference

# Trace entire script
bash -x script.sh

# Trace a specific section
set -x
# ... suspicious code ...
set +x

# Syntax check without running
bash -n script.sh

# Static analysis
shellcheck script.sh

# Custom debug function
debug() { [[ "${DEBUG:-0}" == "1" ]] && echo "[DEBUG] $*" >&2; }

---

Prerequisites

• Comfortable with variables, functions, and control flow (Chapters 1–23)
• A terminal with Bash 4+ installed
• Optional: ShellCheck installed locally

Let’s squash some bugs! Start with Lesson 01 — set -x (xtrace).