シェルスクリプトのヘルプ表示設計｜--helpと--versionとusage関数で使い方を自己文書化する方法

この記事のポイント

・usage関数はヒアドキュメントで書くとヘルプ本文を一元管理できる
・--helpは標準出力（stdout）に出力して終了コード0で終わる
・引数エラーは標準エラー出力（stderr）に出力して終了コード2で終わる
・--versionは冒頭の変数1つを変更するだけで更新できる設計にする

#!/bin/bash

usage() {
  cat <<'EOF'
使い方: backup.sh [オプション] 送信元ディレクトリ

説明:
  指定ディレクトリを /backup 配下にコピーします。

オプション:
  -h, --help       このヘルプを表示して終了する
  -v, --version    バージョンを表示して終了する
  -d, --dry-run    実行内容を表示するだけでコピーしない

引数:
  送信元ディレクトリ  バックアップ対象のパス（必須）

例:
  backup.sh /var/www
  backup.sh --dry-run /var/www
EOF
}

# 引数チェックの先頭で --help を処理する
case "$1" in
  -h|--help)
    usage     # 標準出力（stdout）に出力
    exit 0    # 正常終了
    ;;
esac

# 引数が1つ以上なければエラー
if [ $# -lt 1 ]; then
  echo "エラー: 送信元ディレクトリを指定してください" >&2
  usage >&2   # usage も stderr に出す
  exit 2      # 使い方の誤りは終了コード2
fi

#!/bin/bash
readonly SCRIPT_NAME="backup.sh"
readonly VERSION="1.2.0"

usage() {
  cat <<'EOF'
使い方: backup.sh [オプション] 送信元ディレクトリ
...
EOF
}

case "$1" in
  -h|--help)
    usage
    exit 0
    ;;
  -v|--version)
    echo "${SCRIPT_NAME} version ${VERSION}"
    exit 0
    ;;
esac

#!/bin/bash
# backup.sh - ディレクトリのバックアップスクリプト
readonly SCRIPT_NAME="$(basename "$0")"
readonly VERSION="1.0.0"

usage() {
  cat <<'EOF'
使い方: backup.sh [オプション] 送信元ディレクトリ

説明:
  指定ディレクトリを /backup 配下にコピーします。

オプション:
  -h, --help       このヘルプを表示して終了する
  -v, --version    バージョンを表示して終了する
  -d, --dry-run    実行内容を表示するだけでコピーしない

引数:
  送信元ディレクトリ  バックアップ対象のパス（必須）

例:
  backup.sh /var/www
  backup.sh --dry-run /var/www
EOF
}

# --help / --version は最優先で処理する
case "$1" in
  -h|--help)
    usage
    exit 0
    ;;
  -v|--version)
    echo "${SCRIPT_NAME} version ${VERSION}"
    exit 0
    ;;
esac

# 引数チェック
if [ $# -lt 1 ]; then
  echo "${SCRIPT_NAME}: エラー: 送信元ディレクトリを指定してください" >&2
  usage >&2
  exit 2
fi

SRC_DIR="$1"

if [ ! -d "${SRC_DIR}" ]; then
  echo "${SCRIPT_NAME}: エラー: ディレクトリが存在しません: ${SRC_DIR}" >&2
  exit 1
fi

# 以降に実際の処理を書く
echo "バックアップ対象: ${SRC_DIR}"

# --help を渡したとき（stdout に出てくる）
$ ./backup.sh --help
使い方: backup.sh [オプション] 送信元ディレクトリ

説明:
  指定ディレクトリを /backup 配下にコピーします。

オプション:
  -h, --help       このヘルプを表示して終了する
  -v, --version    バージョンを表示して終了する
  -d, --dry-run    実行内容を表示するだけでコピーしない

引数:
  送信元ディレクトリ  バックアップ対象のパス（必須）

例:
  backup.sh /var/www
  backup.sh --dry-run /var/www

# 引数なしで実行したとき（stderr に出てくる）
$ ./backup.sh 2>/tmp/err.txt; cat /tmp/err.txt
backup.sh: エラー: 送信元ディレクトリを指定してください
使い方: backup.sh [オプション] 送信元ディレクトリ
...

# 終了コードの確認
$ ./backup.sh --help; echo $?
（ヘルプが出る）
0
$ ./backup.sh; echo $?
（エラーが stderr に出る）
2

# NG: usage を stderr に流している
-h|--help)
  usage >&2
  exit 0
  ;;

# NG: 使い方の誤りなのに exit 1 にしている
if [ $# -lt 1 ]; then
  usage >&2
  exit 1   # 処理エラーと区別がつかない
fi

# NG: usage 関数の中に exit を書いている
usage() {
  cat <<'EOF'
...
EOF
  exit 1   # usage を呼ぶだけしたいときに必ず終了してしまう
}