bash-master

Bash スクリプティングの習得

対象範囲とプラットフォームの前提

このスキルは、Linux、macOS、Windows 上の WSL、Git Bash / MSYS2、Bash ベースのコンテナイメージなど、Bash が動作するあらゆる環境でBash 自体を対象とします。ネイティブの PowerShellは対象外です。PowerShell スクリプトは別の言語なので、powershell-master を使用してください。Windows では、bash-master は Git Bash、WSL、または同様の Bash 環境内で Bash を実行していることを前提とし、その結果生じる MSYS のパス変換に関する癖にも対応します。

リポジトリの規約

プロジェクトレベルの規約（ツール呼び出し時の Windows バックスラッシュ、ドキュメント作成の規律など）は、エージェント本体と windows-path-master プラグインに記載されています。このスキルは Bash の内容に焦点を当てます。ここでその定型説明を重複させないでください。

クイックリファレンス

#!/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 の移植性をすばやく確認する方法：

# 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

このスキルを使う場面

必ず有効にしてください：

• Bash／シェルスクリプトの作成または変更
• 既存スクリプトのレビューまたはリファクタリング
• シェルスクリプトの不具合のデバッグ
• DevOps オートメーション、CI/CD パイプライン、システム管理
• 環境をまたいだ Bash の移植性（Linux <-> macOS <-> WSL <-> Git Bash <-> コンテナ）

次の場合はこのスキルを使わないでください：

• PowerShell スクリプト — powershell-master を使用してください
• Batch（.cmd／.bat）スクリプト
• スクリプト作成に関係しない一般的なコマンドのヘルプ

基本原則

1. 安全を最優先する

すべてのスクリプトの先頭に、安全のための前置きを記述してください：

#!/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 と Bash

あらゆる UNIX sh で実行する必要がある場合	#!/bin/sh を使い、[[ ]]、配列、プロセス置換は使わない
Bash を搭載した最新の Linux／macOS	#!/usr/bin/env bash を使い、[[ ]]、配列、正規表現を優先する
Alpine／最小構成のコンテナ	Bash を明示的にインストールするか、POSIX 準拠の sh で記述する

3. クォート

# 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

すべてのスクリプトで shellcheck を実行してください。警告を無効にする場合は、理由を示すコメントを付けてください：# shellcheck disable=SC2086 reason: intentional word splitting。

クォートとスタイルに関する表全体は references/best_practices.md を、よくある落とし穴については references/patterns_antipatterns.md を参照してください。

プラットフォーム固有の考慮事項

Git Bash / MSYS2（Windows）

Git Bash は Unix 形式の引数を Windows パスに自動変換します。これが Windows で発生するクロスプラットフォーム Bash の不具合のうち、最も大きな原因です。

# 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

Git Bash と Windows のパスに関する詳細は、references/windows-git-bash-paths.md に記載されています。

Linux

GNU coreutils、/proc、systemd との統合を利用します。[[ "$OSTYPE" == "linux-gnu"* ]] で検出します。

macOS

BSD ユーティリティの動作は GNU と異なります。よくある注意点：sed -i ''（空文字列が必要）、date のフラグの違い、標準の macOS では readlink -f が利用できないこと。

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

WSL

実質的には Linux です。Windows のファイルシステムは /mnt/c/ にマウントされます。grep -qi microsoft /proc/version で検出します。

コンテナ

Alpine イメージには /bin/sh（BusyBox）のみが含まれています。POSIX 準拠のスクリプトを記述するか、apk add bash を実行してください。コンテナの初期化に関する注意点：PID 1 は子プロセスを回収し、シグナルを処理する必要があります。[ -f /.dockerenv ] または [ -n "$KUBERNETES_SERVICE_HOST" ] で検出します。

移植可能なプラットフォーム検出テンプレート

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

プラットフォームごとの詳細な表（BSD と GNU の coreutils フラグの違い、WSL のネットワーク、コンテナの初期化パターン）は references/platform_specifics.md に記載されています。

ベストプラクティス（概要）

関数の設計、エラー処理、入力検証、引数の解析、ロギングなど、パターンの詳細は references/in-depth-patterns.md に記載されています。主なルールは以下のとおりです：

• 関数ごとに担当する処理を一つにし、ローカル変数は最初に宣言し、入力を検証し、エラー時にはゼロ以外を返します。
• 定数には UPPER_CASE、ローカル変数には lower_case を使い、変更しない値には readonly を指定します。
• 終了コードは必ず確認します（if ! cmd、||、トラップ、または一元管理された error_exit ヘルパーを使います）。
• 外部からの入力はすべて、空かどうか、形式、長さ、文字種を検証します。
• getopts または case ベースの引数パーサーを使い、不正な入力では使用方法を表示して終了コード 1 で終了します。
• ログレベルに対応したロガーを使い、標準エラー出力に書き込みます。

セキュリティ、パフォーマンス、テスト、デバッグ、高度なパターン

これらの各トピックについては、references/in-depth-patterns.md に専用のセクションがあります。

トピック	内容
セキュリティ	コマンドインジェクションの防止、パストラバーサル対策、権限管理、安全な一時ファイル
パフォーマンス	サブシェルの回避、Bash 組み込みコマンドと外部コマンドの使い分け、プロセス置換、配列操作
テスト	BATS による単体テスト、統合テストのパターン、CI/CD との連携
デバッグ	set -x、PS4、条件付きデバッグヘルパー、トレースとプロファイリング
高度なパターン	安全な設定ファイルの解析、並列処理、シグナル処理、バックオフ付きリトライ

これらのトピックの標準的なコードテンプレートが必要なときは、いつでも該当するリファレンスを参照してください。

リファレンスファイル

• references/platform_specifics.md - プラットフォームごとの違いと回避策の詳細
• references/best_practices.md - 業界標準とガイドラインの包括的な解説
• references/patterns_antipatterns.md - よくあるパターンと落とし穴、およびその解決策
• references/windows-git-bash-paths.md - Git Bash / MSYS のパス変換に関するリファレンス
• references/in-depth-patterns.md - 関数設計、セキュリティ、パフォーマンス、テスト、デバッグ、高度なパターン
• references/resources.md - 公式ドキュメント、スタイルガイド、ツール、学習用リンク

成功基準

このスキルを使って作成した Bash スクリプトは、次の条件を満たす必要があります。

1. 警告なしで shellcheck を通過する
2. set -euo pipefail で始まる
3. すべての変数展開を引用符で囲む
4. -h／--help で使い方を表示する
5. テスト可能な関数に分割する
6. 空の入力、存在しないファイル、予期しない引数に対応する
7. サポート対象とするすべてのプラットフォーム（Linux/macOS/WSL/Git Bash/container）で実行できる
8. Google Shell Style Guide に準拠する
9. 終了時にクリーンアップする（trap EXIT）
10. ロジックが単純でない場合は、BATS で単体テストする

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

トラブルシューティング

別のプラットフォームでスクリプトが失敗する

• checkbashisms script.sh を実行して、移植性のない構文を見つけます。
• command -v tool を実行して、必要なツールがインストールされていることを確認します。
• GNU と BSD のコマンドオプションの違いを確認します（sed --version など）。

ShellCheck の警告

• ルールの説明を読みます（shellcheck -W SC2086）。
• 根本的な問題を修正します。ルールを無効にするのは、理由をコメントで説明できる場合に限ります。

対話的な実行では動くが、cron では失敗する

• cron の PATH は最小限です。PATH を明示的に設定します。
• 絶対パスを使います。
• 標準出力と標準エラー出力をリダイレクトします：./script.sh >> /tmp/cron.log 2>&1。

パフォーマンスの問題

• time でプロファイリングします。
• set -x を有効にして、時間のかかる処理を特定します。
• 可能な場合は、外部コマンドの呼び出しを Bash 組み込みコマンドに置き換えます。