ShellCheck 設定とスタティック分析

シェルスクリプトの品質を向上させ、一般的な落とし穴をキャッチし、スタティックコード分析によってベストプラクティスを強制するための ShellCheck の設定と使用に関する包括的なガイドです。

このスキルを使用する場合

• CI/CDパイプラインでシェルスクリプトのリンティングを設定する場合
• 既存のシェルスクリプトの問題を分析する場合
• ShellCheck のエラーコードと警告を理解する場合
• プロジェクトの特定の要件に合わせて ShellCheck を設定する場合
• 開発ワークフローに ShellCheck を統合する場合
• 誤検知を抑制しルールセットを設定する場合
• 一貫したコード品質基準を強制する場合
• スクリプトを品質ゲートに対応させるために移行する場合

ShellCheck の基本

ShellCheck とは？

ShellCheck は、シェルスクリプトを分析して問題のあるパターンを検出するスタティック分析ツールです。以下をサポートしています：

• Bash、sh、dash、ksh、およびその他の POSIX シェル
• 100以上の異なる警告とエラー
• ターゲットシェルとフラグの設定
• エディタと CI/CD システムとの統合

インストール

# macOS with Homebrew
brew install shellcheck

# Ubuntu/Debian
apt-get install shellcheck

# ソースからのインストール
git clone https://github.com/koalaman/shellcheck.git
cd shellcheck
make build
make install

# インストール確認
shellcheck --version

設定ファイル

.shellcheckrc (プロジェクトレベル)

プロジェクトルートに .shellcheckrc を作成します：

# ターゲットシェルの指定
shell=bash

# オプションチェックの有効化
enable=avoid-nullary-conditions
enable=require-variable-braces

# 特定の警告を無効化
disable=SC1091
disable=SC2086

環境変数

# デフォルトシェルターゲットの設定
export SHELLCHECK_SHELL=bash

# 厳密モードを有効化
export SHELLCHECK_STRICT=true

# 設定ファイルの場所を指定
export SHELLCHECK_CONFIG=~/.shellcheckrc

ShellCheck の一般的なエラーコード

SC1000-1099: パーサーエラー

# SC1004: バックスラッシュ継続後に改行がない
echo hello\
world  # エラー - 行継続が必要

# SC1008: 演算子 `==` の無効なデータ
if [[ $var =  "value" ]]; then  # == の前にスペースがある
    true
fi

SC2000-2099: シェルの問題

# SC2009: grep|grep の代わりに pgrep や pidof の使用を検討
ps aux | grep -v grep | grep myprocess  # 代わりに pgrep を使用

# SC2012: `ls` は閲覧用のみ使用。確実な出力には `find` を使用
for file in $(ls -la)  # より良い方法: find またはグロビングを使用

# SC2015: && や || の代わりに if-then-else を使用
[[ -f "$file" ]] && echo "found" || echo "not found"  # より明確でない

# SC2016: 単一引用符内では式は展開されない
echo '$VAR'  # リテラル $VAR、変数展開ではない

# SC2026: この単語は非標準。他のシェル用スクリプトで使用する場合
# POSIXLY_CORRECT を設定

SC2100-2199: クォート問題

# SC2086: グロビングと単語分割を防ぐため二重引用符を使用
for i in $list; do  # より良い方法: for i in $list または for i in "$list"
    echo "$i"
done

# SC2115: パス内のリテラルなチルダは展開されない。代わりに $HOME を使用
~/.bashrc  # 文字列内では "$HOME/.bashrc" を使用

# SC2181: 間接的なリストではなく `if` で直接終了コードをチェック
some_command
if [ $? -eq 0 ]; then  # より良い方法: if some_command; then

# SC2206: 単語分割またはIFSの設定を防ぐため引用符を使用
array=( $items )  # より良い方法: array=( $items )

SC3000-3999: POSIX 準拠の問題

# SC3010: POSIX sh では 'cond && foo' の代わりに 'case' を使用
[[ $var == "value" ]] && do_something  # POSIX ではない

# SC3043: POSIX sh では 'local' は定義されていない
function my_func() {
    local var=value  # 一部のシェルでは POSIX ではない
}

実践的な設定例

最小設定 (厳密な POSIX)

#!/bin/bash
# 最大限の互換性に向けて設定

shellcheck \
  --shell=sh \
  --external-sources \
  --check-sourced \
  script.sh

開発設定 (Bash と緩やかなルール)

#!/bin/bash
# Bash 開発向けに設定

shellcheck \
  --shell=bash \
  --exclude=SC1091,SC2119 \
  --enable=all \
  script.sh

CI/CD 統合設定

#!/bin/bash
set -Eeuo pipefail

# すべてのシェルスクリプトを分析し、問題で失敗
find . -type f -name "*.sh" | while read -r script; do
    echo "Checking: $script"
    shellcheck \
        --shell=bash \
        --format=gcc \
        --exclude=SC1091 \
        "$script" || exit 1
done

プロジェクト用 .shellcheckrc

# 分析対象のシェル方言
shell=bash

# オプションチェックの有効化
enable=avoid-nullary-conditions,require-variable-braces,check-unassigned-uppercase

# 特定の警告を無効化
# SC1091: ソースされたファイルをフォローしない (多くの誤検知)
disable=SC1091

# SC2119: function_name -- (arguments) の代わりに function_name を使用
disable=SC2119

# コンテキスト用にソースするための外部ファイル
external-sources=true

統合パターン

プリコミットフック設定

#!/bin/bash
# .git/hooks/pre-commit

#!/bin/bash
set -e

# このコミットで変更されたすべてのシェルスクリプトを検索
git diff --cached --name-only | grep '\.sh$' | while read -r script; do
    echo "Linting: $script"

    if ! shellcheck "$script"; then
        echo "ShellCheck failed on $script"
        exit 1
    fi
done

GitHub Actions ワークフロー

name: ShellCheck

on: [push, pull_request]

jobs:
  shellcheck:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Run ShellCheck
        run: |
          sudo apt-get install shellcheck
          find . -type f -name "*.sh" -exec shellcheck {} \;

GitLab CI パイプライン

shellcheck:
  stage: lint
  image: koalaman/shellcheck-alpine
  script:
    - find . -type f -name "*.sh" -exec shellcheck {} \;
  allow_failure: false

ShellCheck 違反への対応

特定の警告の抑制

#!/bin/bash

# 行全体の警告を無効化
# shellcheck disable=SC2086
for file in $(ls -la); do
    echo "$file"
done

# スクリプト全体の無効化
# shellcheck disable=SC1091,SC2119

# 複数の警告を無効化 (形式は異なる場合があります)
command_that_fails() {
    # shellcheck disable=SC2015
    [ -f "$1" ] && echo "found" || echo "not found"
}

# source ディレクティブの特定のチェックを無効化
# shellcheck source=./helper.sh
source helper.sh

一般的な違反と修正

SC2086: 単語分割を防ぐため二重引用符を使用

# 問題
for i in $list; do done

# 解決方法
for i in $list; do done  # $list が既に引用されている場合、または
for i in "${list[@]}"; do done  # list が配列の場合

SC2181: 終了コードを直接チェック

# 問題
some_command
if [ $? -eq 0 ]; then
    echo "success"
fi

# 解決方法
if some_command; then
    echo "success"
fi

SC2015: && || の代わりに if-then を使用

# 問題
[ -f "$file" ] && echo "exists" || echo "not found"

# 解決方法 - より明確な意図
if [ -f "$file" ]; then
    echo "exists"
else
    echo "not found"
fi

SC2016: 単一引用符内では式は展開されない

# 問題
echo 'Variable value: $VAR'

# 解決方法
echo "Variable value: $VAR"

SC2009: grep の代わりに pgrep を使用

# 問題
ps aux | grep -v grep | grep myprocess

# 解決方法
pgrep -f myprocess

パフォーマンス最適化

複数ファイルの確認

#!/bin/bash

# 順序付きチェック
for script in *.sh; do
    shellcheck "$script"
done

# 並列チェック (高速)
find . -name "*.sh" -print0 | \
    xargs -0 -P 4 -n 1 shellcheck

結果のキャッシング

#!/bin/bash

CACHE_DIR=".shellcheck_cache"
mkdir -p "$CACHE_DIR"

check_script() {
    local script="$1"
    local hash
    local cache_file

    hash=$(sha256sum "$script" | cut -d' ' -f1)
    cache_file="$CACHE_DIR/$hash"

    if [[ ! -f "$cache_file" ]]; then
        if shellcheck "$script" > "$cache_file" 2>&1; then
            touch "$cache_file.ok"
        else
            return 1
        fi
    fi

    [[ -f "$cache_file.ok" ]]
}

find . -name "*.sh" | while read -r script; do
    check_script "$script" || exit 1
done

出力フォーマット

デフォルトフォーマット

shellcheck script.sh

# 出力:
# script.sh:1:3: warning: foo is referenced but not assigned. [SC2154]

GCC フォーマット (CI/CD 用)

shellcheck --format=gcc script.sh

# 出力:
# script.sh:1:3: warning: foo is referenced but not assigned.

JSON フォーマット (パース用)

shellcheck --format=json script.sh

# 出力:
# [{"file": "script.sh", "line": 1, "column": 3, "level": "warning", "code": 2154, "message": "..."}]

クワイエットフォーマット

shellcheck --format=quiet script.sh

# 問題が見つかった場合はゼロ以外で返す、それ以外は出力なし

ベストプラクティス

1. CI/CD で ShellCheck を実行 - マージ前に問題をキャッチ
2. ターゲットシェル用に設定 - bash を sh として分析しない
3. 除外を文書化 - なぜ違反が抑制されているかを説明
4. 違反に対応 - 警告を無効にするだけではない
5. 厳密モードを有効化 - --enable=all を慎重に除外して使用
6. 定期的に更新 - ShellCheck を最新に保つ
7. プリコミットフックを使用 - プッシュ前にローカルで問題をキャッチ
8. エディタと統合 - 開発中にリアルタイムフィードバックを取得