Bash coding

Bash / Shell Best Practices

Comprehensive guide for writing high-quality, idiomatic, and robust Bash/POSIX shell scripts. Contains 134 rules across 12 categories, prioritized by impact to guide LLMs in code generation and refactoring.

When to Apply

Reference these guidelines when:

• Writing new Bash scripts or shell functions
• Reviewing shell scripts for correctness and security
• Debugging variable scoping, quoting, or exit code issues
• Refactoring legacy shell scripts to modern standards
• Writing scripts that must run on both Linux and macOS
• Choosing between Bash features and POSIX-compatible alternatives
• Setting up CI/CD with ShellCheck and Bats testing
• Handling user input, secrets, or temporary files securely

Bash 5.x & Modern Shell Features

This skill targets Bash 5.x (released 2019) while noting POSIX compatibility. Key features to leverage:

• Associative arrays (declare -A): string-keyed maps for configuration, caching, dispatch tables (Bash 4.0+)
• Namerefs (declare -n, local -n): safe indirect variable/array access, replacing eval (Bash 4.3+)
• Process substitution (<(cmd), >(cmd)): pipe without subshells, preserve variable state (Bash 4.0+)
• Here-strings (<<<): single-string stdin without pipes or forks (Bash 4.0+)
• [[ ]] conditional: regex matching (=~), pattern matching (==), safe unquoted variables
• globstar (shopt -s globstar): recursive **/*.txt glob patterns (Bash 4.0+)
• nullglob / failglob: control glob behavior for empty matches
• extglob: extended patterns (@(), !(), +(), *(), ?())
• readarray/mapfile: read file/command output directly into arrays
• BASH_REMATCH: capture regex groups from [[ =~ ]] matching
• EPOCHSECONDS / EPOCHREALTIME: wall-clock timestamps without date fork (Bash 5.0+)
• BASH_SOURCE vs $0: reliably determine script location regardless of how it's invoked
• Subshell vs command grouping: (cmd) is a subshell (variable changes lost), { cmd; } is in-process

For POSIX sh (#!/bin/sh, dash, ash, busybox sh), avoid all of the above and see port-avoid-bashisms.

Rule Categories by Priority

Priority	Category	Impact	Prefix	Rules
1	Variable Handling & Quoting	CRITICAL	var-	14
2	Error Handling & Exit Codes	CRITICAL	err-	13
3	Input/Output & Redirection	HIGH	io-	12
4	Security	HIGH	sec-	11
5	Function Design	HIGH	fn-	11
6	Portability (POSIX vs Bash)	HIGH	port-	11
7	Naming & Style Conventions	MEDIUM	name-	11
8	Arrays & Data Structures	MEDIUM	arr-	9
9	Testing (Bats/shellspec)	MEDIUM	test-	10
10	Debugging & Logging	MEDIUM	debug-	9
11	Performance & Efficiency	MEDIUM	perf-	9
12	Anti-patterns	REFERENCE	anti-	14

---

Quick Reference

1. Variable Handling & Quoting (CRITICAL)

• var-always-quote - Always quote variable expansions: "$var" not $var
• var-brace-variables - Use ${var} for disambiguation and clarity
• var-default-values - Use ${var:-default} and ${var:=default} for defaults
• var-local-in-functions - Declare function variables with local
• var-readonly-constants - Use readonly or declare -r for constants
• var-uppercase-env - UPPER_CASE for environment variables and globals
• var-null-vs-unset - Use ${var+isset} vs ${var-unset} for existence checks
• var-indirect-reference - Use declare -n (nameref) instead of eval
• var-no-eval-expand - Never use eval for variable expansion
• var-arrays-cautious - Use arrays for lists; don't misuse strings with spaces
• var-no-glob-wordsplitting - Set IFS carefully; disable word splitting for safety
• var-prefix-suffix-remove - Use ${var#prefix}, ${var%suffix}, ${var//pattern/replacement}
• var-length-count - Use ${#var} for string length, ${#arr[@]} for array size
• var-avoid-export-in-loop - Don't export variables inside loops unnecessarily

2. Error Handling & Exit Codes (CRITICAL)

• err-errexit-set - Use set -euo pipefail at top of scripts
• err-pipefail-required - Always use set -o pipefail to catch pipe errors
• err-check-exit-status - Check $? after critical commands
• err-trap-errors - Use trap '...' ERR for error handling
• err-trap-exit-cleanup - Use trap '...' EXIT for cleanup
• err-meaningful-exit - Exit with meaningful non-zero codes
• err-avoid-ignore-errors - Don't use || true to ignore errors without comment
• err-command-exists - Check command -v before using external tools
• err-set-e-cautious - Understand set -e edge cases in conditionals
• err-no-unchecked-cd - Always check cd success: cd dir || exit 1
• err-mkdir-parent - Use mkdir -p to avoid "already exists" errors
• err-return-over-exit-fn - Use return in functions, exit only at top level
• err-dry-run-pattern - Support --dry-run in destructive scripts

3. Input/Output & Redirection (HIGH)

• io-heredoc-quote - Quote heredoc delimiter to prevent expansion: <<'EOF'
• io-stderr-redirect - Redirect stderr explicitly: 2>/dev/null or 2>&1
• io-read-while-pipe - Use while IFS= read -r line pattern correctly
• io-process-substitution - Use <(cmd) and >(cmd) for piping without subshells
• io-avoid-cat-pipe - Avoid cat file | cmd; use cmd < file or cmd file
• io-file-descriptor-management - Use exec for custom file descriptors
• io-here-string - Use <<< for simple string input
• io-tempfile-safely - Use mktemp for temporary files; never hardcode /tmp
• io-null-dev-null - Use /dev/null explicitly; avoid writing to stdout
• io-read-r-preserve - Use read -r to preserve backslashes
• io-no-binary-in-pipe - Don't pipe binary data through text processing
• io-buffered-flush - Use stdbuf or unbuffer when needed for line-buffered pipes

4. Security (HIGH)

• sec-no-unquoted-expansion - Quote all shell expansions to prevent word splitting/glob
• sec-no-eval-user - Never use eval with user-supplied input
• sec-sanitize-input - Validate and sanitize user input before use
• sec-path-injection - Never trust $PATH; use absolute paths or set PATH explicitly
• sec-no-exec-user-test - Don't use user input in command names
• sec-tempfile-race - Use mktemp to avoid TOCTOU races
• sec-suid-cautious - Avoid setuid shell scripts; use sudo instead
• sec-secrets-in-env - Pass secrets via environment, never CLI args
• sec-no-hardcoded-secrets - Use environment variables or secret managers for credentials
• sec-umask-restrictive - Set umask 077 for scripts handling sensitive data
• sec-shellcheck-required - Run shellcheck on all shell scripts

5. Function Design (HIGH)

• fn-return-values - Capture function output with $(...); use return for status
• fn-argument-count - Check $# for required argument count
• fn-argument-names - Name function arguments at top: local name=$1
• fn-main-function - Put main logic in main() function; call at end
• fn-pure-when-possible - Write functions that don't depend on global state
• fn-small-focused - Keep functions small and single-purpose
• fn-no-side-effects - Minimize side effects; document globals modified
• fn-usage-help - Provide usage() function with help text
• fn-option-parsing - Use getopts for argument parsing; avoid manual $1 $2 loops
• fn-library-source - Source library scripts; don't copy-paste functions
• fn-lowercase-names - Use lowercase function names (POSIX namespace safety)

6. Portability (POSIX vs Bash) (HIGH)

• port-shebang-choice - Use #!/usr/bin/env bash for Bash; #!/bin/sh for POSIX
• port-avoid-bashisms - Avoid [[ ]], arrays, ${!ref}, source, == in POSIX sh scripts
• port-posix-test - Use [ ] instead of [[ ]] when portability matters
• port-printf-over-echo - Use printf instead of echo for portable output
• port-no-local-posix - Don't use local in POSIX sh (Bash-ism)
• port-command-v-which - Use command -v over which for command checking
• port-readlink-realpath - Don't assume readlink -f / realpath is available
• port-sed-i-portable - Use sed -i.bak for portable in-place editing
• port-array-alternatives - Use IFS-delimited strings when arrays aren't available
• port-shellcheck-directive - Use ShellCheck directives for bash-only scripts
• port-coproc-portable - Document Bash-specific features when used

7. Naming & Style Conventions (MEDIUM)

• name-variables-uppercase-env - UPPER_CASE for environment/export variables
• name-variables-lowercase-local - lowercase_with_underscores for local vars
• name-functions-lowercase - lowercase function names; avoid UpperCase
• name-constants-readonly - readonly VARIABLE_NAME for constants
• name-files-kebab-case - Use kebab-case.sh for script file names
• name-library-prefix - Prefix library functions with namespace_ (e.g., log_info)
• name-boolean-true-false - Use 0/1 for boolean return values
• name-descriptive-vars - Use descriptive variable names; avoid a, b, c, x
• name-no-reserved-words - Avoid bash keywords as function/variable names
• name-globals-caps - UPPER_CASE for globals in scripts
• name-temp-vars-prefix - Prefix temp variables with _ to mark as internal

8. Arrays & Data Structures (MEDIUM)

• arr-declare-arrays - Use declare -a for indexed, declare -A for associative
• arr-expand-properly - Use "${arr[@]}" to expand arrays with proper quoting
• arr-iterate-keys - Iterate associative array keys with "${!arr[@]}"
• arr-append-elements - Use arr+=("new") to append to arrays
• arr-length-count - Use ${#arr[@]} for array length
• arr-no-spaces-in-keys - Use sensible keys for associative arrays
• arr-pass-to-function - Pass arrays by name with declare -n (nameref)
• arr-slice-subset - Use ${arr[@]:offset:length} for array slicing
• arr-read-into-array - Use readarray/mapfile for reading lines into array

9. Testing (Bats/shellspec) (MEDIUM)

• test-bats-framework - Use Bats (Bash Automated Testing System) for testing
• test-run-helper - Use Bats run helper to capture output and status
• test-assert-output - Use [ "$output" = "expected" ] and [ "$status" -eq 0 ]
• test-setup-teardown - Use setup() and teardown() for test fixtures
• test-mock-commands - Override functions or use stub scripts for mocking
• test-temp-dirs - Create and clean test directories in setup/teardown
• test-one-assertion - Test one behavior per test case
• test-skip-not-installed - Skip tests when dependencies not installed
• test-shellcheck-build - Run ShellCheck as part of the test suite
• test-ci-integration - Output TAP format for CI integration

10. Debugging & Logging (MEDIUM)

• debug-set-x-trace - Use set -x for command tracing; wrap in subshell
• debug-ps4-enhanced - Set enhanced PS4 for file:line:function traces
• debug-trap-debug - Use trap '...' DEBUG for custom debugging
• debug-log-function - Write a log() function with timestamps and levels
• debug-verbose-flag - Support --verbose/-v flag for debug output
• debug-no-echo-debug - Use stderr for debug, stdout for program output
• debug-assert-function - Create assert() helper for runtime checks
• debug-color-output - Use tput or ANSI codes; check if output is terminal
• debug-stack-trace - Print stack trace in ERR trap with caller

11. Performance & Efficiency (MEDIUM)

• perf-avoid-fork - Use builtins ([[ ]], ${var##}, printf) to avoid subshell forks
• perf-avoid-cat-useless - Avoid useless use of cat (UUOC)
• perf-inline-grep - Use Bash pattern matching over grep when possible
• perf-batch-process - Batch operations: git commands, database queries
• perf-parallel-xargs - Use xargs -P for parallel execution
• perf-avoid-subshell-loop - Don't pipe into while; use process substitution
• perf-here-string-speed - Here-strings (<<<) are faster than echo | pipe
• perf-glob-over-find - Use glob patterns over find for simple directory walks
• perf-cache-results - Cache expensive command results in variables

12. Anti-patterns (REFERENCE)

• anti-unquoted-variables - Never leave variable expansions unquoted
• anti-eval-everything - Don't use eval; find builtin alternatives
• anti-bare-variable-in-test - Don't use [ $var = "value" ] on empty var
• anti-pipe-while-subshell - Don't modify variables in pipe while loops (subshell issue)
• anti-ls-in-for - Never use for f in $(ls); use globs: for f in *
• anti-backticks - Use $() over backticks for command substitution
• anti-newlines-in-names - Don't create files/vars with spaces or newlines
• anti-cd-without-check - Always check cd success
• anti-echo-in-function-output - Don't echo debug info in functions that return data
• anti-global-variable-everywhere - Don't use global variables for everything
• anti-source-without-path - Don't source scripts without specifying path
• anti-single-brackets-bash - Don't use [ ] for compound tests in Bash (use [[ ]])
• anti-rm-rf-asterisk-danger - Never use rm -rf $VAR/* without validating $VAR
• anti-interactive-suppress - Don't use yes | in scripts; handle interaction properly

---

Recommended Shell Settings

#!/usr/bin/env bash
# Safer bash defaults — include at top of every script
set -euo pipefail
IFS=$'\n\t'

# Additional safety options (opt-in)
shopt -s nullglob          # Non-matching globs → empty (not literal *)
shopt -s inherit_errexit   # Subshells inherit errexit (Bash 4.4+)
shopt -s shift_verbose     # shift errors when count exceeds $#

# For debuggable scripts:
# shopt -s failglob        # Non-matching globs → error (stricter than nullglob)

---

How to Use

This skill provides rule identifiers for quick reference. When generating or reviewing shell scripts:

1. Check relevant category based on task type
2. Apply rules with matching prefix
3. Prioritize CRITICAL > HIGH > MEDIUM > REFERENCE
4. Read rule files in rules/ for detailed examples with Bad/Good code

Rule Application by Task

Task	Primary Categories
New script skeleton	err-, fn-, name-
Variable handling	var-, sec-
Function writing	fn-, var-
File/pipe processing	io-, perf-
Security review	sec-, anti-
Cross-platform script	port-, name-
Test writing	test-, debug-
Debugging failures	debug-, err-
Code review	anti-, sec-

---

Related Skills

• design-patterns — choosing and implementing GoF/idiomatic patterns in shell scripts (pipeline/filter, command dispatch).
• security-review — cross-language security/correctness review methodology (phases, finding format, severity guidance) applies to shell-script reviews; it does not yet ship a dedicated shell bug-class reference file, so apply the general workflow to injection, unsafe eval/word-splitting, and TOCTOU risks.

Sources

This skill synthesizes best practices from:

• Google Shell Style Guide
• ShellCheck Wiki
• Bash Hackers Wiki
• Wooledge BashGuide
• POSIX Shell Command Language
• Production codebases: Git, Docker, Homebrew, various CI/CD pipelines
• Community conventions and ShellCheck diagnostics