git:20260314.9629b35 to git:20260823.869f02b

---

name: shell-scripting

description: >-

Shell script conventions, defensive patterns, and correctness rules:

strict mode, quoting, portability, error handling, and common pitfalls.

Invoke whenever task involves any interaction with shell scripts —

writing, reviewing, debugging, or understanding .sh, .bash, .zsh files.

---

# Shell Scripting

Write defensively. Shell defaults are hostile — unquoted variables split, unset variables vanish silently, failed

commands continue. Every rule here exists to counteract a specific shell default that causes bugs.

## References

Extended examples, code patterns, and lookup tables for the rules below.

- **Strict mode, error handling, traps, debugging** — [`${CLAUDE_SKILL_DIR}/references/strict-mode.md`]: errexit

caveats, pipefail examples, trap patterns, temp file safety, debugging techniques

- **Quoting rules, word splitting, globbing** — [`${CLAUDE_SKILL_DIR}/references/quoting.md`]: Three quoting mechanisms,

`"$@"` vs `"$*"`, array expansion, printf vs echo, nested quoting

- **POSIX sh vs bash, portable constructs** — [`${CLAUDE_SKILL_DIR}/references/portability.md`]: Feature comparison, GNU

vs BSD tool differences, portable pattern catalog

- **Argument parsing, getopts, validation** — [`${CLAUDE_SKILL_DIR}/references/arguments.md`]: getopts template, manual

long-option parsing, validation patterns, usage messages, stdin detection

- **Common shell scripting mistakes** — [`${CLAUDE_SKILL_DIR}/references/pitfalls.md`]: Iteration pitfalls, variable

pitfalls, test pitfalls, pipeline pitfalls, arithmetic traps

- **Pure bash/sh alternatives to external commands** — [`${CLAUDE_SKILL_DIR}/references/builtins.md`]: Parameter

expansion, replacing sed/cut/basename/expr, arrays, read patterns, arithmetic

## Script Header

Every bash script starts with:

```bash

#!/usr/bin/env bash

set -euo pipefail

```

- **Shebang:** Use `#!/usr/bin/env bash` — not `#!/bin/bash`. The `env` lookup is more portable across systems where

bash is not at `/bin/bash`.

- **`set -e` (errexit):** Exit on command failure. Understand the exceptions: commands in `if`/`while` conditions, left

side of `&&`/`||`, and negated commands (`!`) do not trigger errexit.

- **`set -u` (nounset):** Error on unset variables. Use `${VAR:-default}` for optional variables.

- **`set -o pipefail`:** Pipeline returns the rightmost failing command's exit code, not the last command's.

- **For POSIX sh scripts:** Use `#!/bin/sh`. Drop `pipefail` (not POSIX). Use `set -eu` with caution — `set -e` behavior

varies across sh implementations.

```bash

#!/usr/bin/env bash

set -euo pipefail

#

# deploy.sh — Build and deploy the application to staging.

```

## Quoting

Quoting is the single most important discipline. Unquoted variables undergo word splitting (breaks on IFS characters)

and pathname expansion (glob characters match filenames). Both are silent and devastating.

### Core Rules

- **Always double-quote variable expansions:** `"$var"`, `"${var}"`.

- **Always double-quote command substitutions:** `"$(command)"`.

- **Use `"$@"` to pass arguments through.** Never `$*` or `$@` unquoted. `"$@"` preserves each argument as a separate

word. `"$*"` joins them.

- **Quote array expansions:** `"${arr[@]}"` expands each element as a separate word. Unquoted `${arr[@]}` undergoes word

splitting.

- **Leave globs unquoted:** `for f in *.txt` — the glob must expand. But always quote variables inside the loop: `"$f"`.

- **Leave `[[ ]]` right-hand patterns unquoted** when doing glob or regex matching. Quote the right side for literal

string comparison.

- **Use single quotes for literal strings** that need no expansion: `grep 'pattern' file`.

- **Use `printf` instead of `echo`** for data output. `echo` interprets `-n`, `-e` as options on some platforms.

`printf '%s\n' "$var"` is always safe.

### When Quoting Is Not Needed

- Right side of assignment: `var=$other` (no splitting in assignment context)

- Inside `(( ))` arithmetic: `(( x + y ))`

- Inside `[[ ]]` on the left side: `[[ $var == pattern ]]`

- Integer special variables: `$?`, `$#`, `$$` (guaranteed no spaces)

- `case` word: `case $var in ...`

## Variable Handling

- **Naming:** lowercase with underscores for local variables (`file_path`, `line_count`). UPPER_CASE for

exported/environment variables and constants (`PATH`, `MAX_RETRIES`).

- **Declare constants with `readonly`:**

```bash

readonly CONFIG_DIR="/etc/myapp"

```

- **Use `local` in functions** to prevent variable leakage into global scope. Declare and assign on separate lines when

capturing command output:

```bash

local result

result=$(some_command)

```

Combined `local result=$(cmd)` masks the exit code — `local` always returns 0.

- **Default values:** Use `${VAR:-default}` to provide defaults without modifying the variable. Use `${VAR:=default}` to

set and use.

- **Required variables:** Use `${VAR:?error message}` to abort if unset.

- **Arrays for lists:** Use bash arrays instead of space-delimited strings.

```bash

files=("file one.txt" "file two.txt")

command "${files[@]}"

```

## Error Handling

- **Check every command that can fail.** Use `|| exit 1`, `|| return 1`, or explicit `if` blocks. Especially `cd`,

`mkdir`, `rm`, `cp`, `mv`.

```bash

cd "$dir" || exit 1

```

- **Trap for cleanup.** Use `trap` on EXIT for reliable cleanup:

```bash

tmpfile=$(mktemp) || exit 1

trap 'rm -f "$tmpfile"' EXIT

```

- **Use `mktemp` for temp files.** Never hardcoded temp paths. Always clean up via trap.

- **Error messages to stderr:**

```bash

die() { printf '%s\n' "$1" >&2; exit "${2:-1}"; }

```

- **Exit codes:** Return 0 for success, non-zero for failure. Use meaningful codes: 1 for general error, 2 for usage

error, 64+ for application-specific errors (following sysexits convention).

- **Never use `set -e` as a substitute for error handling.** It has many edge cases. Use it as a safety net, but still

check critical commands explicitly.

## Functions

- **Declare with `name() { ... }`** — no `function` keyword (it's not POSIX and adds nothing in bash).

- **Use `local` for all function variables.** Bash functions share the caller's scope by default — every undeclared

variable is global.

- **Return values via exit code** (0 = success, non-zero = failure) or via stdout. Never rely on global variables for

function output.

- **Separate `local` declaration from command substitution:**

```bash

my_func() {

local output

output=$(some_command) || return 1

}

```

- **Put all functions before executable code.** Only `set` statements, source commands, and constants should precede

function definitions.

- **Use `main` for scripts with multiple functions.** Call `main "$@"` as the last line. This keeps the entry point

obvious and lets all variables be local.

```bash

main() {

local arg="$1"

# ...

}

main "$@"

```

## Control Flow

### Conditionals

- **Use `[[ ]]` in bash** — it prevents word splitting, supports `&&`/`||` inside the test, and enables pattern/regex

matching. In POSIX sh, use `[ ]` with all variables quoted.

- **Use `(( ))` for numeric comparisons:**

```bash

if (( count > 10 )); then ...

```

In POSIX sh: `[ "$count" -gt 10 ]`.

- **Use `==` in `[[ ]]` and `=` in `[ ]`** for string equality.

- **Test empty/non-empty explicitly:** `[[ -z "$var" ]]` and `[[ -n "$var" ]]` — not `[[ "$var" ]]`.

- **Never use `&&`/`||` as if/then/else:**

```bash

# WRONG — cmd3 runs if cmd2 fails, even when cmd1 succeeds

cmd1 && cmd2 || cmd3

# RIGHT

if cmd1; then cmd2; else cmd3; fi

```

### Loops

- **Never parse `ls` output.** Use globs:

```bash

for f in ./*.txt; do

[[ -e "$f" ]] || continue

process "$f"

done

```

- **Use `while read` for line-oriented input:**

```bash

while IFS= read -r line; do

printf '%s\n' "$line"

done < file

```

The `IFS=` prevents leading/trailing whitespace trimming. The `-r` prevents backslash interpretation.

- **Use process substitution to avoid subshell variable loss:**

```bash

while IFS= read -r line; do

(( count++ ))

done < <(command)

echo "$count" # preserved

```

- **Use `find -print0` with `read -d ''`** for filenames with special characters:

```bash

while IFS= read -r -d '' file; do

process "$file"

done < <(find . -type f -print0)

```

### Case Statements

- **`case` for multi-way branching:**

```bash

case "$1" in

start) do_start ;;

stop) do_stop ;;

restart) do_stop; do_start ;;

*) die "Unknown command: $1" ;;

esac

```

- **Indent patterns by 2 spaces** from `case`. Put `;;` on the same line as the action for one-liners, on its own line

for multi-line actions.

## Input Handling

- **Use `getopts` for short options.** It is POSIX, handles combined flags (`-vf`), and manages `OPTARG`/`OPTIND`

correctly.

- **Use manual parsing for long options.** `while (( $# > 0 )); do case` loop with explicit `--` handling.

- **Always handle `--`** to end option processing — prevents filenames starting with `-` from being interpreted as

options.

- **Always use `--` when passing variables to commands:**

```bash

rm -- "$file"

grep -- "$pattern" "$file"

```

- **Prefix globs with `./`** to prevent files named `-rf` from becoming options:

```bash

for f in ./*; do

rm -- "$f"

done

```

- **Provide a `usage()` function** for any script that takes arguments. Print to stderr and exit with code 64

(EX_USAGE).

- **Validate arguments early.** Check counts, types, file existence before starting work.

- **Detect stdin vs terminal:** `[[ -t 0 ]]` tests whether stdin is a terminal.

## Formatting

- **Indent with 2 spaces.** No tabs (except in `<<-` heredocs).

- **Maximum line length: 80 characters.** Use `\` continuation or heredocs for long strings.

- **`; then` and `; do` on the same line** as `if`/`for`/`while`:

```bash

if [[ -f "$file" ]]; then

for item in "${arr[@]}"; do

while read -r line; do

```

- **Split long pipelines** one per line with `|` on the continuation line:

```bash

command1 \

| command2 \

| command3

```

- **Use `$(command)` not backticks.** `$()` nests cleanly and is readable. Backticks require escaping and don't nest.

- **Prefer `${var}` braces** for all variables except positional parameters (`$1`-`$9`) and special parameters (`$?`,

`$#`, etc.).

## Portability

- **Choose your target.** Decide upfront whether you need POSIX sh compatibility or can require bash.

- **If targeting bash:** use `#!/usr/bin/env bash`, use `[[ ]]`, arrays, and process substitution freely. Specify

minimum bash version if using 4.0+ features (associative arrays, `mapfile`, case modification).

- **If targeting POSIX sh:** use `#!/bin/sh`, use `[ ]` with quoted variables, no arrays, no `[[ ]]`, no `(( ))`, no

`local` (technically non-POSIX but widely supported), no process substitution.

- **macOS ships bash 3.2 permanently.** If targeting macOS without requiring Homebrew bash, avoid bash 4+ features.

- **Avoid GNU-specific tool options** when portability matters: `sed -i`, `grep -P`, GNU `date` flags. Document the

dependency when GNU tools are required.

- **Use `command -v`** to check if a program is available — not `which` (which is not a builtin and behaves differently

across systems).

## ShellCheck Integration

- **Run ShellCheck on all scripts.** It catches quoting errors, portability issues, and common pitfalls automatically.

- **Use a directive comment for intentional violations:**

```bash

# shellcheck disable=SC2086

word_split_is_intentional $var

```

- **Specify shell dialect** if the shebang is absent or ambiguous:

```bash

# shellcheck shell=bash

```

- **Common ShellCheck codes to know:**

- SC2086: Double quote to prevent globbing and word splitting

- SC2046: Quote this to prevent word splitting

- SC2034: Variable appears unused (might be exported or sourced)

- SC2155: Declare and assign separately to avoid masking return values

- SC2164: Use `cd ... || exit` in case `cd` fails

## Application

**When writing shell scripts:** Apply all rules silently. Produce clean, defensive code. Use strict mode, quote

everything, handle errors, use arrays for lists.

**When reviewing shell scripts:** Cite the specific rule violated. Show the fix inline. Prioritize: quoting bugs > error

handling gaps > style issues.

## Integration

- `the-coder` provides the overall coding workflow (discover, plan, verify)

- Language plugins (golang, javascript) handle language-specific tooling

- This skill handles shell-specific correctness and defensive patterns

Quote everything. Handle every error. Trust nothing.