bash-pro

Use this skill when

Writing or reviewing Bash scripts for automation, CI/CD, or ops
Hardening shell scripts for safety and portability

Do not use this skill when

You need POSIX-only shell without Bash features
The task requires a higher-level language for complex logic
You need Windows-native scripting (PowerShell)

Instructions

Define script inputs, outputs, and failure modes.
Apply strict mode and safe argument parsing.
Implement core logic with defensive patterns.
Add tests and linting with Bats and ShellCheck.

Safety

Treat input as untrusted; avoid eval and unsafe globbing.
Prefer dry-run modes before destructive actions.

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

Compatibility & Portability

Use
```
#!/usr/bin/env bash
```
shebang for portability across systems
Check Bash version at script start:
```
(( BASH_VERSINFO[0] >= 4 && BASH_VERSINFO[1] >= 4 ))
```
for Bash 4.4+ features
Validate required external commands exist:
```
command -v jq &>/dev/null || exit 1
```

Detect platform differences:

case "$(uname -s)" in Linux*) ... ;; Darwin*) ... ;; esac

Handle GNU vs BSD tool differences (e.g.,
```
sed -i
```
vs
```
sed -i ''
```
)
Test scripts on all target platforms (Linux, macOS, BSD variants)
Document minimum version requirements in script header comments
Provide fallback implementations for platform-specific features
Use built-in Bash features over external commands when possible for portability
Avoid bashisms when POSIX compliance is required, document when using Bash-specific features

Readability & Maintainability

Use long-form options in scripts for clarity:
```
--verbose
```
instead of
```
-v
```
Employ consistent naming: snake_case for functions/variables, UPPER_CASE for constants
Add section headers with comment blocks to organize related functions
Keep functions under 50 lines; refactor larger functions into smaller components
Group related functions together with descriptive section headers
Use descriptive function names that explain purpose:
```
validate_input_file
```
not
```
check_file
```
Add inline comments for non-obvious logic, avoid stating the obvious
Maintain consistent indentation (2 or 4 spaces, never tabs mixed with spaces)
Place opening braces on same line for consistency:
```
function_name() {
```
Use blank lines to separate logical blocks within functions
Document function parameters and return values in header comments
Extract magic numbers and strings to named constants at top of script

Safety & Security Patterns

Declare constants with
```
readonly
```
to prevent accidental modification
Use
```
local
```
keyword for all function variables to avoid polluting global scope
Implement
```
timeout
```
for external commands:
```
timeout 30s curl ...
```
prevents hangs
Validate file permissions before operations:
```
[[ -r "$file" ]] || exit 1
```
Use process substitution
```
<(command)
```
instead of temporary files when possible
Sanitize user input before using in commands or file operations
Validate numeric input with pattern matching:
```
[[ $num =~ ^[0-9]+$ ]]
```
Never use
```
eval
```
on user input; use arrays for dynamic command construction
Set restrictive umask for sensitive operations:
```
(umask 077; touch "$secure_file")
```
Log security-relevant operations (authentication, privilege changes, file access)
Use
```
--
```
to separate options from arguments:
```
rm -rf -- "$user_input"
```
Validate environment variables before using:
```
: "${REQUIRED_VAR:?not set}"
```
Check exit codes of all security-critical operations explicitly
Use
```
trap
```
to ensure cleanup happens even on abnormal exit

Performance Optimization

Avoid subshells in loops; use
```
while read
```
instead of
```
for i in $(cat file)
```
Use Bash built-ins over external commands:
```
[[ ]]
```
instead of
```
test
```
,
```
${var//pattern/replacement}
```
instead of
```
sed
```
Batch operations instead of repeated single operations (e.g., one
```
sed
```
with multiple expressions)
Use
```
mapfile
```
/
```
readarray
```
for efficient array population from command output
Avoid repeated command substitutions; store result in variable once
Use arithmetic expansion
```
$(( ))
```
instead of
```
expr
```
for calculations
Prefer
```
printf
```
over
```
echo
```
for formatted output (faster and more reliable)
Use associative arrays for lookups instead of repeated grepping
Process files line-by-line for large files instead of loading entire file into memory
Use
```
xargs -P
```
for parallel processing when operations are independent

Documentation Standards

Implement
```
--help
```
and
```
-h
```
flags showing usage, options, and examples
Provide
```
--version
```
flag displaying script version and copyright information
Include usage examples in help output for common use cases
Document all command-line options with descriptions of their purpose
List required vs optional arguments clearly in usage message
Document exit codes: 0 for success, 1 for general errors, specific codes for specific failures
Include prerequisites section listing required commands and versions
Add header comment block with script purpose, author, and modification date
Document environment variables the script uses or requires
Provide troubleshooting section in help for common issues
Generate documentation with
```
shdoc
```
from special comment formats
Create man pages using
```
shellman
```
for system integration
Include architecture diagrams using Mermaid or GraphViz for complex scripts

Modern Bash Features (5.x)

Bash 5.0: Associative array improvements,
```
${var@U}
```
uppercase conversion,
```
${var@L}
```
lowercase
Bash 5.1: Enhanced
```
${parameter@operator}
```
transformations,
```
compat
```
shopt options for compatibility
Bash 5.2:
```
varredir_close
```
option, improved
```
exec
```
error handling,
```
EPOCHREALTIME
```
microsecond precision

Check version before using modern features:

[[ ${BASH_VERSINFO[0]} -ge 5 && ${BASH_VERSINFO[1]} -ge 2 ]]

Use
```
${parameter@Q}
```
for shell-quoted output (Bash 4.4+)
Use
```
${parameter@E}
```
for escape sequence expansion (Bash 4.4+)
Use
```
${parameter@P}
```
for prompt expansion (Bash 4.4+)
Use
```
${parameter@A}
```
for assignment format (Bash 4.4+)
Employ
```
wait -n
```
to wait for any background job (Bash 4.3+)
Use
```
mapfile -d delim
```
for custom delimiters (Bash 4.4+)

CI/CD Integration

GitHub Actions: Use
```
shellcheck-problem-matchers
```
for inline annotations

Pre-commit hooks: Configure

.pre-commit-config.yaml

with

shellcheck

shfmt

checkbashisms

Matrix testing: Test across Bash 4.4, 5.0, 5.1, 5.2 on Linux and macOS
Container testing: Use official bash:5.2 Docker images for reproducible tests
CodeQL: Enable shell script scanning for security vulnerabilities
Actionlint: Validate GitHub Actions workflow files that use shell scripts
Automated releases: Tag versions and generate changelogs automatically
Coverage reporting: Track test coverage and fail on regressions

Example workflow:

shellcheck *.sh && shfmt -d *.sh && bats test/

Security Scanning & Hardening

SAST: Integrate Semgrep with custom rules for shell-specific vulnerabilities
Secrets detection: Use
```
gitleaks
```
or
```
trufflehog
```
to prevent credential leaks
Supply chain: Verify checksums of sourced external scripts
Sandboxing: Run untrusted scripts in containers with restricted privileges
SBOM: Document dependencies and external tools for compliance
Security linting: Use ShellCheck with security-focused rules enabled
Privilege analysis: Audit scripts for unnecessary root/sudo requirements
Input sanitization: Validate all external inputs against allowlists
Audit logging: Log all security-relevant operations to syslog
Container security: Scan script execution environments for vulnerabilities

Observability & Logging

Structured logging: Output JSON for log aggregation systems
Log levels: Implement DEBUG, INFO, WARN, ERROR with configurable verbosity
Syslog integration: Use
```
logger
```
command for system log integration
Distributed tracing: Add trace IDs for multi-script workflow correlation
Metrics export: Output Prometheus-format metrics for monitoring
Error context: Include stack traces, environment info in error logs
Log rotation: Configure log file rotation for long-running scripts
Performance metrics: Track execution time, resource usage, external call latency

Example:

log_info() { logger -t "$SCRIPT_NAME" -p user.info "$*"; echo "[INFO] $*" >&2; }

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-core or shellspec with TAP output
CI/CD pipeline configurations (GitHub Actions, GitLab CI) for automated testing
Documentation generated with shdoc and man pages with shellman
Structured project layout with reusable library functions and dependency management
Static analysis configuration files (.shellcheckrc, .shfmt.toml, .editorconfig)
Performance benchmarks and profiling reports for critical workflows
Security review with SAST, secrets scanning, and vulnerability reports
Debugging utilities with trace modes, structured logging, and observability
Migration guides for Bash 3→5 upgrades and legacy modernization
Package distribution configurations (Homebrew formulas, deb/rpm specs)
Container images for reproducible execution environments

Essential Tools

Static Analysis & Formatting

ShellCheck: Static analyzer with
```
enable=all
```
and
```
external-sources=true
```
configuration
shfmt: Shell script formatter with standard config (
```
-i 2 -ci -bn -sr -kp
```
)
checkbashisms: Detect bash-specific constructs for portability analysis
Semgrep: SAST with custom rules for shell-specific security issues
CodeQL: GitHub's security scanning for shell scripts

Testing Frameworks

bats-core: Maintained fork of Bats with modern features and active development
shellspec: BDD-style testing framework with rich assertions and mocking
shunit2: xUnit-style testing framework for shell scripts
bashing: Testing framework with mocking support and test isolation

Modern Development Tools

bashly: CLI framework generator for building command-line applications
basher: Bash package manager for dependency management
bpkg: Alternative bash package manager with npm-like interface
shdoc: Generate markdown documentation from shell script comments
shellman: Generate man pages from shell scripts

CI/CD & Automation

pre-commit: Multi-language pre-commit hook framework
actionlint: GitHub Actions workflow linter
gitleaks: Secrets scanning to prevent credential leaks
Makefile: Automation for lint, format, test, and release 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)

Dependency Management

Package managers: Use
```
basher
```
or
```
bpkg
```
for installing shell script dependencies
Vendoring: Copy dependencies into project for reproducible builds
Lock files: Document exact versions of dependencies used
Checksum verification: Verify integrity of sourced external scripts
Version pinning: Lock dependencies to specific versions to prevent breaking changes
Dependency isolation: Use separate directories for different dependency sets
Update automation: Automate dependency updates with Dependabot or Renovate
Security scanning: Scan dependencies for known vulnerabilities

Example:

basher install username/repo@version

bpkg install username/repo -g

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

Associative Arrays:

declare -A config=([host]="localhost" [port]="8080")

for complex data structures

Parameter Expansion:
```
${filename%.sh}
```
remove extension,
```
${path##*/}
```
basename,
```
${text//old/new}
```
replace all

Signal Handling:

trap cleanup_function SIGHUP SIGINT SIGTERM

for graceful shutdown

Command Grouping:
```
{ cmd1; cmd2; } > output.log
```
share redirection,
```
( cd dir && cmd )
```
use subshell for isolation

Co-processes:

coproc proc { cmd; }; echo "data" >&"${proc[1]}"; read -u "${proc[0]}" result

for bidirectional pipes

Here-documents:
```
cat <<-'EOF'
```
with
```
-
```
strips leading tabs, quotes prevent expansion
Process Management:
```
wait $pid
```
to wait for background job,
```
jobs -p
```
list background PIDs
Conditional Execution:
```
cmd1 && cmd2
```
run cmd2 only if cmd1 succeeds,
```
cmd1 || cmd2
```
run cmd2 if cmd1 fails
Brace Expansion:
```
touch file{1..10}.txt
```
creates multiple files efficiently
Nameref Variables:
```
declare -n ref=varname
```
creates reference to another variable (Bash 4.3+)
Improved Error Trapping:
```
set -Eeuo pipefail; shopt -s inherit_errexit
```
for comprehensive error handling
Parallel Execution:
```
xargs -P $(nproc) -n 1 command
```
for parallel processing with CPU core count
Structured Output:
```
jq -n --arg key "$value" '{key: $key}'
```
for JSON generation
Performance Profiling: Use
```
time -v
```
for detailed resource usage or
```
TIMEFORMAT
```
for custom timing

References & Further Reading

Style Guides & Best Practices

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
Bash Hackers Wiki - Comprehensive Bash documentation and advanced techniques
Defensive BASH Programming - Modern defensive programming patterns

Tools & Frameworks

ShellCheck - Static analysis tool and extensive wiki documentation
shfmt - Shell script formatter with detailed flag documentation
bats-core - Maintained Bash testing framework
shellspec - BDD-style testing framework for shell scripts
bashly - Modern Bash CLI framework generator
shdoc - Documentation generator for shell scripts

Security & Advanced Topics

Bash Security Best Practices - Security-focused shell script patterns
Awesome Bash - Curated list of Bash resources and tools
Pure Bash Bible - Collection of pure bash alternatives to external commands