bash-expert

name	bash-expert
description	Use when implementing bash functionality with production-grade patterns and safeguards.
metadata	{"hermes":{"tags":["codex-agent","languages-runtime"],"source":"codex-field-kit/languages-runtime"}}

Bash Expert

Focus Areas

• Defensive programming with strict error handling
• POSIX compliance and cross-platform portability
• Safe argument parsing and input validation
• Robust file operations and temporary resource management
• Process orchestration and pipeline safety
• Production-grade logging and error reporting
• Comprehensive testing with Bats framework
• Static analysis with ShellCheck and formatting with shfmt
• Modern Bash 5.x features and best practices
• CI/CD integration and automation workflows

Approach

• Always use strict mode with set -Eeuo pipefail and proper error trapping
• Quote all variable expansions to prevent word splitting and globbing issues
• Prefer arrays and proper iteration over unsafe patterns like for f in $(ls)
• Use [[ ]] for Bash conditionals, fall back to [ ] for POSIX compliance
• Implement comprehensive argument parsing with getopts and usage functions
• Create temporary files and directories safely with mktemp and cleanup traps
• Prefer printf over echo for predictable output formatting
• Use command substitution $() instead of backticks for readability
• Implement structured logging with timestamps and configurable verbosity
• Design scripts to be idempotent and support dry-run modes
• Use shopt -s inherit_errexit for better error propagation in Bash 4.4+
• Employ IFS=$'\n\t' to prevent unwanted word splitting on spaces
• Validate inputs with : "${VAR:?message}" for required environment variables
• End option parsing with -- and use rm -rf -- "$dir" for safe operations
• Support --trace mode with set -x opt-in for detailed debugging
• Use xargs -0 with NUL boundaries for safe subprocess orchestration
• Employ readarray/mapfile for safe array population from command output
• Implement robust script directory detection: SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
• Use NUL-safe patterns: find -print0 | while IFS= read -r -d '' file; do ...; done

Quality Checklist

• Scripts pass ShellCheck static analysis with minimal suppressions
• Code is formatted consistently with shfmt using standard options
• Comprehensive test coverage with Bats including edge cases
• All variable expansions are properly quoted
• Error handling covers all failure modes with meaningful messages
• Temporary resources are cleaned up properly with EXIT traps
• Scripts support --help and provide clear usage information
• Input validation prevents injection attacks and handles edge cases
• Scripts are portable across target platforms (Linux, macOS)
• Performance is adequate for expected workloads and data sizes

Output

• Production-ready Bash scripts with defensive programming practices
• Comprehensive test suites using Bats framework with TAP output
• CI/CD pipeline configurations for automated testing and validation
• Documentation including usage examples and deployment instructions
• Structured project layout with reusable library functions
• Static analysis configuration files (shellcheckrc, .shfmt.conf)
• Performance benchmarks for critical automation workflows
• Security review focusing on input validation and privilege handling
• Debugging utilities with trace modes and verbose logging
• Migration guides for converting legacy scripts to modern practices

Essential Tools

• ShellCheck: Static analyzer with enable=all and external-sources=true configuration
• shfmt: Shell script formatter with standard config (-i 2 -ci -bn -sr -kp)
• Bats: TAP-compliant testing framework for Bash scripts
• Makefile: Automation for lint, format, and test workflows

Common Pitfalls to Avoid

• for f in $(ls ...) causing word splitting/globbing bugs (use find -print0 | while IFS= read -r -d '' f; do ...; done)
• Unquoted variable expansions leading to unexpected behavior
• Relying on set -e without proper error trapping in complex flows
• Using echo for data output (prefer printf for reliability)
• Missing cleanup traps for temporary files and directories
• Unsafe array population (use readarray/mapfile instead of command substitution)
• Ignoring binary-safe file handling (always consider NUL separators for filenames)

Advanced Techniques

• Error Context: Use trap 'echo "Error at line $LINENO: exit $?" >&2' ERR for debugging
• Safe Temp Handling: trap 'rm -rf "$tmpdir"' EXIT; tmpdir=$(mktemp -d)
• Version Checking: (( BASH_VERSINFO[0] >= 5 )) before using modern features
• Binary-Safe Arrays: readarray -d '' files < <(find . -print0)
• Function Returns: Use declare -g result for returning complex data from functions

References & Further Reading

• Google Shell Style Guide - Comprehensive style guide covering quoting, arrays, and when to use shell
• Bash Pitfalls - Catalog of common Bash mistakes and how to avoid them
• ShellCheck - Static analysis tool and extensive wiki documentation
• shfmt - Shell script formatter with detailed flag documentation