bash

name	bash
description	Bash Shell Script Development Guidelines

Bash Shell Script Development Guidelines

High-quality, maintainable bash shell scripts following industry best practices.

Critical Requirements

• ALWAYS include shebang #!/usr/bin/env bash at the top of every script
• ALWAYS use set -euo pipefail for error handling
• ALWAYS quote variables to prevent word splitting: "$variable" not $variable
• ALWAYS check if a command exists before using it with command -v
• ALWAYS run shellcheck and shfmt before completing any script
• NEVER use eval unless absolutely necessary and after careful security review
• NEVER parse ls output - use globs or find instead
• NO EMOJIS in scripts or comments

Quality Gates (NON-NEGOTIABLE)

Before completing any bash script, ALL must pass:

shellcheck script.sh    # REQUIRED - must pass with no errors or warnings
shfmt -d script.sh      # REQUIRED - must have no diff (properly formatted)

To auto-format a script:

shfmt -w script.sh

Fix all shellcheck errors and warnings. Do not use # shellcheck disable= directives unless absolutely necessary and justified.

Script Structure

Standard Template

#!/usr/bin/env bash

# Script: script_name.sh
# Description: Brief description of what the script does
# Usage: script_name.sh [options] [arguments]

set -euo pipefail

# Configuration - declare and assign separately to avoid SC2155
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_DIR
SCRIPT_NAME="$(basename "${BASH_SOURCE[0]}")"
readonly SCRIPT_NAME

# Color codes for output (optional)
readonly RED='\033[0;31m'
readonly GREEN='\033[0;32m'
readonly YELLOW='\033[1;33m'
readonly NC='\033[0m' # No Color

# Functions
usage() {
    cat <<EOF
Usage: ${SCRIPT_NAME} [OPTIONS] [ARGUMENTS]

Description of what this script does.

OPTIONS:
    -h, --help      Show this help message
    -v, --verbose   Enable verbose output
    -d, --debug     Enable debug mode

ARGUMENTS:
    arg1            Description of argument 1
    arg2            Description of argument 2

EXAMPLES:
    ${SCRIPT_NAME} --verbose file.txt
    ${SCRIPT_NAME} -d input.txt output.txt
EOF
}

log_info() {
    echo -e "${GREEN}[INFO]${NC} $*" >&2
}

log_warn() {
    echo -e "${YELLOW}[WARN]${NC} $*" >&2
}

log_error() {
    echo -e "${RED}[ERROR]${NC} $*" >&2
}

cleanup() {
    # Cleanup code here (temp files, etc.)
    :
}

main() {
    # Main script logic here
    :
}

# Trap errors and cleanup
trap cleanup EXIT
trap 'log_error "Script failed at line $LINENO"' ERR

# Parse arguments and run main
main "$@"

Best Practices

Error Handling

1. Use set -euo pipefail:

   • set -e: Exit on error
   • set -u: Exit on undefined variable
   • set -o pipefail: Exit on pipe failure

2. Check command exit codes explicitly when needed:

   if ! command_that_might_fail; then
       log_error "Command failed"
       exit 1
   fi
   

3. Use trap for cleanup:

   trap cleanup EXIT
   trap 'log_error "Error at line $LINENO"' ERR
   

Variable Quoting

1. Always quote variables:

   # Good
   cp "$source" "$destination"
   
   # Bad
   cp $source $destination
   

2. Quote command substitutions:

   # Good
   result="$(some_command)"
   
   # Bad
   result=$(some_command)
   

3. Use arrays for lists:

   # Good
   files=("file1.txt" "file 2.txt" "file3.txt")
   for file in "${files[@]}"; do
       process "$file"
   done
   
   # Bad
   files="file1.txt file 2.txt file3.txt"
   for file in $files; do
       process $file
   done
   

Conditionals and Comparisons

1. Use [[ ]] instead of [ ]:

   # Good - modern bash
   if [[ "$var" == "value" ]]; then
       echo "Match"
   fi
   

2. Check if variable is set:

   # Check if set and non-empty
   if [[ -n "${var:-}" ]]; then
       echo "Variable is set"
   fi
   
   # Check if unset or empty
   if [[ -z "${var:-}" ]]; then
       echo "Variable is not set"
   fi
   

3. File tests:

   if [[ -f "$file" ]]; then echo "Regular file exists"; fi
   if [[ -d "$dir" ]]; then echo "Directory exists"; fi
   if [[ -x "$script" ]]; then echo "File is executable"; fi
   if [[ -r "$file" ]];   ; 
   

Command Substitution

1. Use $() instead of backticks:

   # Good
   result="$(command)"
   
   # Bad
   result=`command`
   

2. Check if command exists before using:

   if ! command -v jq &> /dev/null; then
       log_error "jq is not installed"
       exit 1
   fi
   

Functions

1. Use local variables:

   process_file() {
       local file="$1"
       local output="${2:-output.txt}"
   
       # Process the file
       cat "$file" > "$output"
   }
   

2. Return values properly:

   # For numeric return codes (0-255)
   check_status() {
       if [[ -f "$1" ]]; then
           return 0  # Success
       else
           return 1  # Failure
       fi
   }
   
   # For string output, use echo
   get_filename() {
       local path="$1"
       echo "$(basename "$path")"
   }
   

Argument Parsing

1. Use getopts for simple cases:

   while getopts "hvd:" opt; do
       case $opt in
           h) usage; exit 0 ;;
           v) verbose=1 ;;
           d) directory="$OPTARG" ;;
           \?) log_error "Invalid option: -$OPTARG"; exit 1 ;;
       esac
   done
   shift $((OPTIND - 1))
   

2. Manual parsing for long options:

   while [[ $# -gt 0 ]]; do
       case $1 in
           -h|--help)
               usage
               exit 0
               ;;
           -v|--verbose)
               verbose=1
               shift
               ;;
           -o|--output)
               output="$2"
               shift 2
               ;;
           *)
               log_error "Unknown option: $1"
               exit 1
               ;;
       esac
   done
   

Common Patterns

Working with Files

1. Read file line by line:

   while IFS= read -r line; do
       echo "Line: $line"
   done < "$file"
   

2. Process files matching pattern:

   # Using glob
   for file in *.txt; do
       [[ -f "$file" ]] || continue
       process "$file"
   done
   
   # Using find for complex patterns
   while IFS= read -r -d '' file; do
       process "$file"
   done < <(find . -name "*.txt" -type f -print0)
   

3. Create temporary files/directories:

   temp_file="$(mktemp)"
   temp_dir="$(mktemp -d)"
   
   cleanup() {
       rm -f "$temp_file"
       rm -rf "$temp_dir"
   }
   trap cleanup EXIT
   

String Manipulation

1. Parameter expansion:

   # Remove prefix/suffix
   filename="${path##*/}"        # basename
   directory="${path%/*}"        # dirname
   extension="${filename##*.}"   # file extension
   basename="${filename%.*}"     # filename without extension
   
   # Default values
   value="${var:-default}"       # Use default if var is unset/empty
   value="${var:=default}"       # Assign default if var is unset/empty
   
   # String replacement
   new="${old/pattern/replacement}"     # Replace first occurrence
   new="${old//pattern/replacement}"    # Replace all occurrences
   

2. String length and substrings:

   length="${#string}"
   substring="${string:0:5}"     # First 5 characters
   substring="${string: -5}"     # Last 5 characters
   

Arrays

1. Array operations:

   # Declaration
   array=("item1" "item2" "item3")
   
   # Access elements
   echo "${array[0]}"           # First element
   echo "${array[@]}"           # All elements
   echo "${#array[@]}"          # Array length
   
   # Iteration
   for item in "${array[@]}"; do
       echo "$item"
   done
   
   # Add elements
   array+=("item4")
   

2. Associative arrays (bash 4+):

   declare -A map
   map["key1"]="value1"
   map["key2"]="value2"
   
   # Iterate
   for key in "${!map[@]}"; do
       echo "$key: ${map[$key]}"
   done
   

Security Considerations

1. Never use user input directly in commands:

   # Bad - command injection vulnerability
   eval "rm $user_input"
   
   # Good - validate and sanitize
   if [[ "$user_input" =~ ^[a-zA-Z0-9_-]+$ ]]; then
       rm -f "$user_input"
   fi
   

2. Use full paths for commands in scripts run as root:

   # Good
   /usr/bin/rm -f "$file"
   
   # Risky if PATH is modified
   rm -f "$file"
   

3. Set secure permissions on sensitive scripts:

   chmod 700 sensitive_script.sh  # Owner only
   chmod 755 public_script.sh     # All can read/execute
   

4. Avoid exposing secrets in process list:

   # Bad - password visible in ps
   mysql -p"$password" -e "SELECT * FROM users"
   
   # Good - use config file
   mysql --defaults-file="$config_file" -e "SELECT * FROM users"
   

Common Anti-Patterns to Avoid

1. Parsing ls output:

   # Bad
   for file in $(ls *.txt); do
       process "$file"
   done
   
   # Good
   for file in *.txt; do
       [[ -f "$file" ]] || continue
       process "$file"
   done
   

2. Unquoted variables:

   # Bad
   if [ $var == $other ]; then
   
   # Good
   if [[ "$var" == "$other" ]]; then
   

3. Using echo for output that might contain flags:

   # Bad - can interpret flags
   echo "$user_input"
   
   # Good
   printf '%s\n' "$user_input"
   

4. Cat abuse (UUOC - Useless Use of Cat):

   # Bad
   cat file.txt | grep pattern
   
   # Good
   grep pattern file.txt
   

5. Not checking if commands exist:

   # Bad
   jq '.field' file.json
   
   
    !  -v jq &> /dev/null; 
       log_error 
        1
   
   jq  file.json
   

Testing and Validation

ShellCheck (REQUIRED)

Always run shellcheck on scripts - all errors and warnings must be fixed:

shellcheck script.sh

Common issues and fixes:

Error	Fix
SC2155	Declare and assign separately: VAR=$(cmd) then readonly VAR
SC2086	Quote the variable: "$var" not $var
SC2046	Quote command substitution: "$(cmd)" not $(cmd)
SC2164	Add `
SC2071	Use -lt/-gt for numbers: [[ $a -lt $b ]] not [[ $a < $b ]]

Avoid using disable directives - fix the underlying issue instead.

shfmt (REQUIRED)

Always format scripts with shfmt:

# Check formatting (shows diff if not formatted)
shfmt -d script.sh

# Auto-format in place
shfmt -w script.sh

Code Review Checklist

• Shebang present and correct (#!/usr/bin/env bash)
• set -euo pipefail used
• All variables quoted properly
• No parsing of ls output
• Functions use local variables
• Error messages go to stderr
• Proper cleanup with trap
• No use of eval without justification
• Command existence checked before use
• Usage/help message provided
• No hardcoded paths
• Array usage for lists of items
• [[ ]] used instead of [ ]
• No security vulnerabilities
• shellcheck passes with no errors or warnings
• shfmt -d shows no diff