🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (
) in file paths, NOT forward slashes (/ ).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx

• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter

• Write tool file_path parameter

• All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• Priority: Update existing README.md files rather than creating new documentation

• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise

• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone

• User preference: Only create additional .md files when user specifically asks for documentation

Bash 5.3 Features (2025)

Overview

Bash 5.3 (released July 2025) introduces significant new features that improve performance, readability, and functionality.

Key New Features

1. In-Shell Command Substitution

New: ${ command; } syntax - Executes without forking a subshell (runs in current shell context):

OLD way (Bash < 5.3) - Creates subshell

output=$(expensive_command)

NEW way (Bash 5.3+) - Runs in current shell, faster

output=${ expensive_command; }

Benefits:

• No subshell overhead (faster)

• Preserves variable scope

• Better performance in loops

Example:

#!/usr/bin/env bash

Traditional approach

count=0 for file in *.txt; do lines=$(wc -l < "$file") # Subshell created ((count += lines)) done

Bash 5.3 approach (faster)

count=0 for file in *.txt; do lines=${ wc -l < "$file"; } # No subshell ((count += lines)) done

2. REPLY Variable Command Substitution

New: ${| command; } syntax - Stores result in REPLY variable:

Runs command, result goes to $REPLY automatically

${| complex_calculation; } echo "Result: $REPLY"

Multiple operations

${| local_var="processing" echo "$local_var: $((42 * 2))" } echo "Got: $REPLY"

Use Cases:

• Avoid variable naming conflicts

• Clean syntax for temporary values

• Standardized result variable

3. Enhanced read Builtin

New: -E option - Uses readline with programmable completion:

Interactive input with tab completion

read -E -p "Enter filename: " filename

User can now tab-complete file paths!

With custom completion

read -E -p "Select environment: " env

Enables full readline features (history, editing)

Benefits:

• Better UX for interactive scripts

• Built-in path completion

• Command history support

4. Enhanced source Builtin

New: -p PATH option - Custom search path for sourcing:

OLD way

source /opt/myapp/lib/helpers.sh

NEW way - Search custom path

source -p /opt/myapp/lib:/usr/local/lib helpers.sh

Respects CUSTOM_PATH instead of current directory

CUSTOM_PATH=/app/modules:/shared/lib source -p "$CUSTOM_PATH" database.sh

Benefits:

• Modular library organization

• Avoid hard-coded paths

• Environment-specific sourcing

5. Enhanced compgen Builtin

New: Variable output option - Store completions in variable:

OLD way - Output to stdout

completions=$(compgen -f)

NEW way - Directly to variable

compgen -v completions_var -f

Results now in $completions_var

Benefits:

• Cleaner completion handling

• No extra subshells

• Better performance

6. GLOBSORT Variable

New: Control glob sorting behavior:

Default: alphabetical sort

echo *.txt

Sort by modification time (newest first)

GLOBSORT="-mtime" echo *.txt

Sort by size

GLOBSORT="size" echo *.txt

Reverse alphabetical

GLOBSORT="reverse" echo *.txt

Options:

• name

• Alphabetical (default)

• reverse

• Reverse alphabetical

• size

• By file size

• mtime

• By modification time

• -mtime

• Reverse modification time

7. BASH_TRAPSIG Variable

New: Signal number variable in traps:

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

BASH_TRAPSIG contains the signal number being handled

handle_signal() { echo "Caught signal: $BASH_TRAPSIG" >&2 case "$BASH_TRAPSIG" in 15) echo "SIGTERM (15) received, shutting down gracefully" ;; 2) echo "SIGINT (2) received, cleaning up" ;; *) echo "Signal $BASH_TRAPSIG received" ;; esac }

trap handle_signal SIGTERM SIGINT SIGHUP

Benefits:

• Reusable signal handlers

• Dynamic signal-specific behavior

• Better logging and debugging

8. Floating-Point Arithmetic

New: fltexpr loadable builtin:

Enable floating-point support

enable -f /usr/lib/bash/fltexpr fltexpr

Perform calculations

fltexpr result = 42.5 * 1.5 echo "$result" # 63.75

Complex expressions

fltexpr pi_area = 3.14159 * 5 * 5 echo "Area: $pi_area"

Use Cases:

• Scientific calculations

• Financial computations

• Avoid external tools (bc, awk)

Performance Improvements

Avoid Subshells

❌ OLD (Bash < 5.3) - Multiple subshells

for i in {1..1000}; do result=$(echo "$i * 2" | bc) process "$result" done

✅ NEW (Bash 5.3+) - No subshells

for i in {1..1000}; do result=${ echo $((i * 2)); } process "$result" done

Performance Gain: ~40% faster in benchmarks

Efficient File Processing

#!/usr/bin/env bash

Process large file efficiently

process_log() { local line_count=0 local error_count=0

while IFS= read -r line; do
    ((line_count++))

    # Bash 5.3: No subshell for grep
    if ${ grep -q "ERROR" <<< "$line"; }; then
        ((error_count++))
    fi
done < "$1"

echo "Processed $line_count lines, found $error_count errors"

}

process_log /var/log/app.log

Migration Guide

Check Bash Version

#!/usr/bin/env bash

Require Bash 5.3+

if ((BASH_VERSINFO[0] < 5 || (BASH_VERSINFO[0] == 5 && BASH_VERSINFO[1] < 3))); then echo "Error: Bash 5.3+ required (found $BASH_VERSION)" >&2 exit 1 fi

Feature Detection

Test for 5.3 features

has_bash_53_features() { # Try using ${ } syntax if eval 'test=${ echo "yes"; }' 2>/dev/null; then return 0 else return 1 fi }

if has_bash_53_features; then echo "Bash 5.3 features available" else echo "Using legacy mode" fi

Gradual Adoption

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

Support both old and new bash

if ((BASH_VERSINFO[0] > 5 || (BASH_VERSINFO[0] == 5 && BASH_VERSINFO[1] >= 3))); then # Bash 5.3+ path result=${ compute_value; } else # Legacy path result=$(compute_value) fi

Best Practices (2025)

Use ${ } for performance-critical loops

for item in "${large_array[@]}"; do processed=${ transform "$item"; } done

Use ${| } for clean temporary values

${| calculate_hash "$file"; } if [[ "$REPLY" == "$expected_hash" ]]; then echo "Valid" fi

Enable readline for interactive scripts

read -E -p "Config file: " config

Use source -p for modular libraries

source -p "$LIB_PATH" database.sh logging.sh

Document version requirements

Requires: Bash 5.3+ for performance features

Compatibility Notes

Bash 5.3 Availability (2025)

Note: Bash 5.3 (released July 2025) is the latest stable version. There is no Bash 5.4 as of October 2025.

• Linux: Ubuntu 24.04+, Fedora 40+, Arch (current)

• macOS: Homebrew (brew install bash )

• Windows: WSL2 with Ubuntu 24.04+

• Containers: bash:5.3 official image

C23 Conformance

Bash 5.3 updated to C23 language standard. Note: K&R style C compilers are no longer supported.

Fallback Pattern

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

Detect bash version

readonly BASH_53_PLUS=$((BASH_VERSINFO[0] > 5 || (BASH_VERSINFO[0] == 5 && BASH_VERSINFO[1] >= 3)))

process_items() { local item for item in "$@"; do if ((BASH_53_PLUS)); then result=${ transform "$item"; } # Fast path else result=$(transform "$item") # Compatible path fi echo "$result" done }

Real-World Examples

Fast Log Parser

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

Parse log file (Bash 5.3 optimized)

parse_log() { local file="$1" local stats_errors=0 local stats_warnings=0 local stats_lines=0

while IFS= read -r line; do
    ((stats_lines++))

    # Fast pattern matching (no subshell)
    ${| grep -q "ERROR" <<< "$line"; } && ((stats_errors++))
    ${| grep -q "WARN" <<< "$line"; }  && ((stats_warnings++))
done < "$file"

echo "Lines: $stats_lines, Errors: $stats_errors, Warnings: $stats_warnings"

}

parse_log /var/log/application.log

Interactive Configuration

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

Interactive setup with readline

setup_config() { echo "Configuration Setup" echo "==================="

# Tab completion for paths
read -E -p "Data directory: " data_dir
read -E -p "Config file: " config_file

# Validate and store
${|
    [[ -d "$data_dir" ]] && echo "valid" || echo "invalid"
}

if [[ "$REPLY" == "valid" ]]; then
    echo "DATA_DIR=$data_dir" > config.env
    echo "CONFIG_FILE=$config_file" >> config.env
    echo "✓ Configuration saved"
else
    echo "✗ Invalid directory" >&2
    return 1
fi

}

setup_config

Resources

• Bash 5.3 Release Notes

• Bash Manual - Command Substitution

• ShellCheck Bash 5.3 Support

Bash 5.3 provides significant performance and usability improvements. Adopt these features gradually while maintaining backwards compatibility for older systems.