git describe

git describe は直近の annotated タグ からコミットの「人間が読める名前」を生成するコマンドです。バージョン文字列の自動生成や CI/CD パイプラインでのリリース管理に欠かせないツールです。

基本的な使い方

# 現在のコミットに最も近い annotated タグを基に名前を生成
git describe

# lightweight タグも対象に含める
git describe --tags

# タグが存在しなくてもコミットハッシュを返す
git describe --always

出力形式

タグから N コミット離れている場合、以下の形式で出力されます。

v1.2.3-4-gabcdef7
  ↑     ↑  ↑
  タグ   コミット数  ハッシュ（g + 短縮形）

• タグ自体を指している場合は v1.2.3 のようにタグ名のみが出力されます。
• コミット数が 0 でも --long を使うと常に長い形式で表示できます。

CI/CD でのバージョン自動生成

多くのプロジェクトで git describe を使ってビルドバージョンを自動的に付与します。

# バージョン文字列を取得してビルドに埋め込む
VERSION=$(git describe --tags --always)
echo "Building version: $VERSION"

# 未コミットの変更があれば -dirty を付与
VERSION=$(git describe --tags --always --dirty)
echo "Version: $VERSION"  # 例: v1.2.3-4-gabcdef7-dirty

ハッシュの短縮桁数を指定する

# ハッシュを8桁で表示
git describe --abbrev=8

# ハッシュを表示しない（タグ名 + コミット数のみ）
git describe --abbrev=0

# --abbrev=0 はタグ名だけを取得したいときに便利
git describe --abbrev=0 --tags

タグをフィルタする

# v で始まるタグだけを対象にする
git describe --match "v*"

# rc タグを除外して安定版タグだけを対象にする
git describe --exclude "*rc*"

よくあるエラーと対処法

# エラー: タグが存在しない場合
git describe
# fatal: No names found, cannot describe anything.

# 対処: --always を使ってハッシュにフォールバック
git describe --always
# abc1234

# または --tags で lightweight タグも対象にする
git describe --tags --always

ヒント

• git describe --tags --always --dirty の組み合わせは「どんな状況でも有効なバージョン文字列を返す」鉄板の書き方です。
• --abbrev=0 を使うと「直近のタグ名だけ」を取得できます。スクリプトでタグを確認したいときに便利です。
• タグが見つからない場合は git tag -a v0.1.0 -m "initial release" で最初のタグを作成してください。