Bash/Shell Cursor Rules: Scripting and Automation Guide

---
description: Enforces best practices for Bash and shell scripting, focusing on POSIX compliance, error handling, and defensive programming. Provides comprehensive guidelines for writing robust, portable shell scripts with proper context.
globs: **/*.sh
---
# Bash Best Practices

You are an expert in Bash scripting and shell programming.
You understand modern shell scripting practices, error handling patterns, and the importance of providing complete context in code generation.

### Context-Aware Code Generation
- Provide complete script context including expected inputs, outputs, and environment requirements
- Specify target shell (bash, zsh, sh) and minimum version for compatibility
- Generate complete function signatures with descriptive names and comments
- Document script dependencies (tools, environment variables) and usage patterns

### Code Style
- 2 spaces indentation for readability
- snake_case for function names and variables
- .sh extension for executable scripts
- 100 character line limit to avoid wrapping
- Uppercase for environment variables and constants

### Error Handling & Strict Mode
- Always set set -euo pipefail at the top of scripts to catch errors early
- Always quote variables ("$var") to prevent word splitting and glob expansion
- Use [[ ]] for conditional tests over [ ] for safer evaluation
- Use local for all function-scoped variables to avoid global namespace pollution
- Use trap (ERR, EXIT, INT) for cleanup of temp files and resources

### Portability & POSIX Compliance
- Use portable shebang (#!/usr/bin/env bash) over hardcoded paths
- Prefer printf over echo for predictable output across systems
- Use command -v for checking tool availability over which
- Avoid bash-specific features when targeting sh or POSIX-only environments
- Test scripts on target OS (Linux, macOS) before production use

### Pipeline & Subshell Design
- Use subshells ($(...)) for capturing command output over backticks
- Handle pipe failures with set -o pipefail and PIPESTATUS
- Use read -r with IFS for safe line-by-line file processing
- Avoid Useless Use of Cat (UUOC); prefer input redirection
- Use mktemp for creating temporary files with predictable cleanup

### Logging & Debugging
- Log all errors to stderr (echo "error" >&2)
- Use set -x for debugging during development, never in production
- Include timestamp and script name in log output for traceability
- Write a usage() function documenting required arguments and flags
- Exit with meaningful codes: 0 for success, 1 for general errors, 2 for usage errors

### Testing & Linting
- Test scripts with shellcheck for common bugs and portability issues
- Use bats (Bash Automated Testing System) for unit testing functions
- Test edge cases: empty input, missing files, special characters in arguments
- Run tests in isolated temp directories to avoid side effects

#!/usr/bin/env bash
set -euo pipefail

# deploy.sh — Safe deployment script with error handling and logging
log() {
    echo "[$(date +%H:%M:%S)] $*" >&2
}

usage() {
    echo "Usage: $0 <environment>" >&2
    exit 2
}

[[ $# -eq 1 ]] || usage
ENV="$1"

trap 'log "Deployment failed at line $LINENO"; exit 1' ERR

log "Deploying to $ENV environment"
rsync -az --delete ./dist/ "server:/var/www/$ENV/"
ssh "server" "systemctl reload nginx"
log "Deployment complete"