bash-expert

Bash Scripting Mastery

Scope and platform contract

This skill targets Bash itself, wherever Bash runs - Linux, macOS, WSL, Git Bash / MSYS2 on Windows, and Bash-based container images. It does not cover native PowerShell: a PowerShell script is a different language and should use powershell-expert. On Windows, bash-expert assumes the user is running Bash inside Git Bash, WSL, or a similar Bash environment, and addresses the MSYS path-translation quirks that result.

Repository conventions

Project-level conventions (Windows backslashes in tool calls, documentation discipline, etc.) live in the agent body and the windows-path-expert plugin. This skill focuses on Bash content; do not duplicate that boilerplate here.

Quick reference

#!/usr/bin/env bash
set -euo pipefail  # Exit on error, undefined vars, pipe failures
IFS=$'\n\t'        # Safe word splitting
# Run shellcheck your_script.sh before deployment.
# Test on every target platform before production.

Bash-portability quick check:

# Linux/macOS:       Full bash features
# Git Bash (Windows): Most features, some system calls missing (no systemd, /proc differs)
# WSL:               Effectively Linux; /mnt/c for Windows filesystem
# Containers:        Depends on base image - alpine ships /bin/sh, not bash
# POSIX mode:        Use /bin/sh and avoid bashisms

When to use this skill

Always activate for:

• Writing or modifying any bash/shell script
• Reviewing or refactoring existing scripts
• Debugging shell script failures
• DevOps automation, CI/CD pipelines, system administration
• Cross-environment Bash portability (Linux <-> macOS <-> WSL <-> Git Bash <-> container)

Do not use this skill for:

• PowerShell scripts - use powershell-expert
• Batch (.cmd/.bat) scripting
• Generic command help unrelated to scripting

Core principles

1. Safety first

Every script should open with the safety preamble:

#!/usr/bin/env bash
set -e            # Exit on any error
set -u            # Exit on undefined variable
set -o pipefail   # Catch failures mid-pipeline
set -E            # Inherit ERR trap into functions
IFS=$'\n\t'       # Avoid word splitting on spaces

readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_NAME="$(basename "${BASH_SOURCE[0]}")"

2. POSIX vs Bash

Need to run on any UNIX sh	#!/bin/sh, no [[ ]], no arrays, no process substitution
Modern Linux/macOS with Bash	#!/usr/bin/env bash, prefer [[ ]], arrays, regex
Alpine/minimal containers	Either install bash explicitly or write POSIX-compliant sh

3. Quoting

# Always quote expansions
process "$file_path"        # correct
process $file_path          # word-splitting bug

# Arrays
files=("file 1.txt" "file 2.txt")
process "${files[@]}"       # each element kept separate
process "${files[*]}"       # joined as one string - usually wrong

4. ShellCheck

Run shellcheck on every script. Only disable warnings with a justification comment: # shellcheck disable=SC2086 reason: intentional word splitting.

See references/best_practices.md for the full quoting/style table and references/patterns_antipatterns.md for the common pitfalls.

Platform-specific considerations

Git Bash / MSYS2 (Windows)

Git Bash auto-converts Unix-style arguments to Windows paths. This is the largest single source of cross-platform Bash bugs on Windows.

# The conversion: /foo becomes C:/Program Files/Git/usr/foo
# Disable per-command:
MSYS_NO_PATHCONV=1 command /path/that/should/stay/unix

# Manual conversion
unix_path=$(cygpath -u "C:\Windows\System32")
win_path=$(cygpath -w "/c/Users/username")

# Detect Git Bash
if [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "mingw"* ]]; then
    : # Git Bash
fi
case "${MSYSTEM:-}" in
    MINGW64|MINGW32|MSYS) : ;;  # MSYS2 / Git Bash environment
esac

# Flags that look like paths
command //e //s   # double-slash to suppress conversion
command -e -s     # or use dash-options

Full Git Bash + Windows path notes live in references/windows-git-bash-paths.md.

Linux

GNU coreutils, /proc, systemd integration. Detect via [[ "$OSTYPE" == "linux-gnu"* ]].

macOS

BSD utilities behave differently from GNU. Most common gotchas: sed -i '' (empty string required), date flags differ, readlink -f not available on stock macOS.

if command -v gsed >/dev/null; then SED=gsed; else SED=sed; fi

WSL

Effectively Linux. The Windows filesystem is mounted at /mnt/c/. Detect via grep -qi microsoft /proc/version.

Containers

Alpine images ship only /bin/sh (BusyBox). Write POSIX-compliant scripts or apk add bash. Container init quirks: PID 1 must reap children and handle signals. Detect via [ -f /.dockerenv ] or [ -n "$KUBERNETES_SERVICE_HOST" ].

Portable platform-detection template

detect_platform() {
    case "$OSTYPE" in
        linux-gnu*)    echo "linux" ;;
        darwin*)       echo "macos" ;;
        msys*|cygwin*) echo "windows" ;;
        *)             echo "unknown" ;;
    esac
}

Full per-platform tables (BSD-vs-GNU coreutils flags, WSL networking, container init patterns) live in references/platform_specifics.md.

Best practices (summary)

The full patterns - function design, error handling, input validation, argument parsing, logging - live in references/in-depth-patterns.md. The headline rules:

• One concern per function; locals declared first; validate input; return non-zero on error.
• Constants UPPER_CASE; locals lower_case; mark immutable values readonly.
• Always check exit codes (if ! cmd, ||, traps, or a central error_exit helper).
• Validate every external input - empty, format, length, charset.
• Use getopts or a case-based argument parser; print usage and exit 1 on bad input.
• Use a leveled logger that writes to stderr.

Security, performance, testing, debugging, advanced patterns

These each have dedicated sections in references/in-depth-patterns.md:

Topic	What it covers
Security	Command-injection prevention, path-traversal guards, privilege management, secure temp files
Performance	Avoiding subshells, bash built-ins vs externals, process substitution, array ops
Testing	BATS unit tests, integration test patterns, CI/CD wiring
Debugging	set -x, PS4, conditional debug helpers, tracing and profiling
Advanced patterns	Safe config parsing, parallel processing, signal handling, retries with backoff

Read that reference any time you need the canonical code template for one of those topics.

Reference files

• references/platform_specifics.md - Detailed platform differences and workarounds
• references/best_practices.md - Comprehensive industry standards and guidelines
• references/patterns_antipatterns.md - Common patterns and pitfalls with solutions
• references/windows-git-bash-paths.md - Git Bash / MSYS path-translation reference
• references/in-depth-patterns.md - Function design, security, performance, testing, debugging, advanced patterns
• references/resources.md - Official docs, style guides, tooling, and learning links

Success criteria

A Bash script written with this skill should:

1. Pass shellcheck with no warnings
2. Begin with set -euo pipefail
3. Quote every variable expansion
4. Print usage on -h/--help
5. Decompose into testable functions
6. Handle empty input, missing files, and unexpected arguments
7. Run on every target platform (Linux/macOS/WSL/Git Bash/container) where it claims support
8. Match the Google Shell Style Guide
9. Clean up on exit (trap EXIT)
10. Be unit-tested with BATS where logic is non-trivial

# Pre-deployment checklist
shellcheck script.sh
bash -n script.sh
bats test/script.bats
./script.sh --help
DEBUG=true ./script.sh

Troubleshooting

Script fails on a different platform

• checkbashisms script.sh to surface non-portable constructs.
• command -v tool to verify a required tool is installed.
• Diff command flags between GNU and BSD (sed --version etc.).

ShellCheck warnings

• Read the rule explanation (shellcheck -W SC2086).
• Fix the underlying issue; only disable a rule with a justification comment.

Works interactively but fails in cron

• Cron has a minimal PATH - set PATH explicitly.
• Use absolute paths.
• Redirect stdout/stderr: ./script.sh >> /tmp/cron.log 2>&1.

Performance issues

• Profile with time.
• Enable set -x to find slow steps.
• Replace external invocations with Bash built-ins where possible.