ddaanet/token-efficient-bash

Token-Efficient Bash Scripting

Write bash scripts that provide automatic progress diagnostics and fail-fast error handling without manual echo statements or verbose error reporting.

The Pattern

For sequential bash commands (3+ steps), use this header with intent comment:

# Intent: high-level description of what this block does
exec 2>&1
set -xeuo pipefail

# Script commands here

Intent comment required: First line must be a comment explaining the block's purpose (before exec 2>&1). This provides context for why the script exists, while set -x handles per-command tracing.

Per-Command Comments Not Needed

The set -x flag eliminates the need for per-command WHAT comments - the traced output documents what each command does:

# Reorganize source files into target directory
exec 2>&1
set -xeuo pipefail

mkdir -p target/
mv source/* target/
ln -s ../target source

Output shows exactly what happens:

+ mkdir -p target/
+ mv source/* target/
+ ln -s ../target source

Each command is printed before execution. No need for # Create directory or # Move files comments after each line. The traced output IS the per-command documentation.

Two types of comments:

• Intent comment (required): First line explains overall purpose of the block
• Per-command comments (not needed): Individual WHAT comments eliminated by set -x tracing
• Exception: Complex logic may still warrant inline comments explaining WHY (business logic, non-obvious decisions), not WHAT (commands being run)

How It Works

exec 2>&1

Redirects stderr to stdout, merging all output into single stream.

Purpose: Ensures tracing output (set -x writes to stderr) appears in correct order with command output.

Result: Unified output stream with interleaved commands and results.

set -xeuo pipefail

Four orthogonal flags:

-x (xtrace):

• Print each command before execution
• Prefixed with + in output
• This is the key to token economy - eliminates echo statements
• Shows actual commands with expanded variables

-e (errexit):

• Exit immediately if any command returns non-zero
• Prevents error cascades
• No need for || exit 1 after every command

-u (nounset):

• Error on undefined variable references
• Catches typos and missing environment variables
• Prevents silent failures from $TYPO expanding to empty string

-o pipefail:

• Pipeline fails if ANY command in pipe fails
• Normally pipes return exit status of last command only
• Example: grep pattern file | wc -l fails if grep fails

When to Use

Use this pattern for:

• Sequential operations (3+ commands)
• File operations requiring error checking (mv, cp, ln, mkdir)
• Multi-step git workflows (add, commit, push)
• Setup/teardown sequences
• Any script where you'd otherwise write echo statements

Do NOT use for:

• Single commands (just run the command)
• Parallel operations (use multiple Bash tool calls)
• Interactive commands (set -x interferes with prompts)
• Large process substitutions (tracing overhead)
• Commands requiring complex error handling (use traditional if/else)

Strict Mode Caveats

Some commands have expected non-zero exits that would trigger set -e. Handle with || true.

Commands with Normal Non-Zero Exits

grep - exits 1 when no match:

# Search for pattern and continue processing
exec 2>&1
set -xeuo pipefail

# grep returns 1 when pattern not found - this is normal
grep "pattern" file.txt || true

# Continue with other commands
echo "Processing complete"

diff - exits 1 when files differ:

# Compare files and continue with other operations
exec 2>&1
set -xeuo pipefail

# diff returns 1 when files differ - expected behavior
diff file1.txt file2.txt || true

# Other commands still fail-fast

Other common cases:

• test / [ / [[ - false condition returns 1
• git diff --exit-code - exits 1 if differences exist
• make with certain targets
• Background jobs that may fail

Bash Arithmetic Expansion

Problem: (( )) returns exit status equal to the expression value.

# Increment counter (BROKEN)
exec 2>&1
set -xeuo pipefail

count=0
((count++))  # FAILS - expression evaluates to 0, triggers set -e

Solution 1: Use || true

# Increment counter with let
exec 2>&1
set -xeuo pipefail

count=0
let count++ || true  # Safe

Solution 2: Use $(( )) (arithmetic substitution, not expansion)

# Increment counter with arithmetic substitution
exec 2>&1
set -xeuo pipefail

count=0
count=$((count + 1))  # Safe - always succeeds

Conditional Logic with Expected Failures

When a command failure is part of normal flow:

# Check configuration and branch on result
exec 2>&1
set -xeuo pipefail

# Check if pattern exists (grep exit 1 is expected)
if grep -q "pattern" config.yaml || true; then
    echo "Pattern found"
else
    echo "Pattern not found"
fi

# Or use grep in condition directly (if handles exit status)
if grep -q "pattern" config.yaml; then
    echo "Found"
fi  # No || true needed in if condition

Worked examples: Read references/examples.md for file operations, git workflow, and setup-with-expected-failures examples with output.

Directory changes: Read references/directory-changes.md for trap-based and subshell approaches to safe directory changes.

Anti-patterns: Read references/anti-patterns.md for common mistakes (redundant error handling, single-command overhead, blanket error suppression).