git tagの使い方 - バージョン管理とリリース

git tagは、特定のコミットに名前を付けて記録するコマンドです。リリースバージョン（v1.0.0など）を管理するために使います。タグは移動しないため、リリース時点のコードを確実に参照できます。

基本的な使い方

タグを作成

bash

# 軽量タグを作成
git tag v1.0.0

# 注釈付きタグを作成（推奨）
git tag -a v1.0.0 -m "Release version 1.0.0"

# 現在のHEADにタグを付ける
git tag -a v1.0.1 -m "Patch release"

タグの一覧を表示

bash

# すべてのタグを表示
git tag

# パターンで絞り込み
git tag -l "v1.*"
git tag -l "v2.0.*"

出力例：

plain

v1.0.0
v1.0.1
v1.1.0
v2.0.0

タグの詳細を確認

bash

# タグの情報を表示
git show v1.0.0

# タグのメタデータのみ表示
git tag -v v1.0.0

タグを削除

bash

# ローカルのタグを削除
git tag -d v1.0.0

# リモートのタグを削除
git push origin --delete v1.0.0
# または
git push origin :refs/tags/v1.0.0

タグをリモートにプッシュ

bash

# 特定のタグをプッシュ
git push origin v1.0.0

# すべてのタグをプッシュ
git push origin --tags

# 注釈付きタグのみプッシュ
git push --follow-tags

軽量タグと注釈付きタグ

軽量タグ（Lightweight Tag）

bash

# 軽量タグを作成
git tag v1.0.0

コミットへの参照のみ
作成者、日付、メッセージなし
一時的なマーカーに使用

注釈付きタグ（Annotated Tag）

bash

# 注釈付きタグを作成
git tag -a v1.0.0 -m "Release version 1.0.0"

完全なGitオブジェクト
作成者、日付、メッセージを含む
GPG署名が可能
リリースには必ず注釈付きタグを使う

違いを確認

bash

# 軽量タグ
git tag v1.0.0-light
git show v1.0.0-light
# コミット情報のみ表示

# 注釈付きタグ
git tag -a v1.0.0-annotated -m "Annotated tag"
git show v1.0.0-annotated
# タグ情報 + コミット情報を表示

出力例：

plain

tag v1.0.0-annotated
Tagger: John Doe <john@example.com>
Date:   Tue Jan 7 10:30:00 2025 +0900

Annotated tag

commit a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
Author: John Doe <john@example.com>
Date:   Tue Jan 7 10:00:00 2025 +0900

    Add new feature

よく使うオプション

-a, --annotate: 注釈付きタグ

bash

git tag -a v1.0.0 -m "Release version 1.0.0"

リリースには必ず使用します。

-m, --message: メッセージを指定

bash

git tag -a v1.0.0 -m "Major release with new features"

エディタを開かずにメッセージを設定できます。

-l, --list: パターンでフィルター

bash

# v1系のタグのみ表示
git tag -l "v1.*"

# betaバージョンのみ
git tag -l "*beta*"

# ワイルドカード使用
git tag -l "v2.0.*"

-d, --delete: タグを削除

bash

# ローカルのタグを削除
git tag -d v1.0.0

-f, --force: 既存のタグを上書き

bash

# タグを移動（非推奨）
git tag -f v1.0.0 new-commit-hash

注意: リモートにプッシュ済みのタグは移動しないでください。

-s, --sign: GPG署名付きタグ

bash

# GPG署名付きタグを作成
git tag -s v1.0.0 -m "Signed release"

セキュアなリリースに使用します。

-v, --verify: 署名を検証

bash

# GPG署名を検証
git tag -v v1.0.0

-n: メッセージを表示

bash

# タグとメッセージを表示
git tag -n

# 最初の3行を表示
git tag -n3

特定のコミットにタグを付ける

過去のコミットにタグを付ける

bash

# コミットハッシュを指定
git tag -a v0.9.0 a1b2c3d -m "Beta release"

# HEADから相対的に指定
git tag -a v0.9.1 HEAD~3 -m "Old release"

ブランチの最新コミットにタグを付ける

bash

# mainブランチの最新にタグ
git tag -a v1.0.0 main -m "Release from main"

# 別のブランチにタグ
git tag -a v2.0.0-beta develop -m "Beta from develop"

リモートとの同期

タグをリモートにプッシュ

bash

# 特定のタグをプッシュ
git push origin v1.0.0

# すべてのタグをプッシュ
git push origin --tags

# 注釈付きタグのみプッシュ（推奨）
git push --follow-tags

リモートのタグを取得

bash

# すべてのタグを取得
git fetch --tags

# または
git fetch origin --tags

リモートのタグを削除

bash

# 方法1
git push origin --delete v1.0.0

# 方法2
git push origin :refs/tags/v1.0.0

# ローカルとリモート両方を削除
git tag -d v1.0.0
git push origin --delete v1.0.0

リモートのタグを確認

bash

# リモートのタグを表示
git ls-remote --tags origin

# または
git fetch --tags
git tag

タグを使った操作

タグをチェックアウト

bash

# タグをチェックアウト（detached HEAD状態）
git checkout v1.0.0

# タグから新しいブランチを作成
git checkout -b hotfix-v1.0.0 v1.0.0

タグの差分を確認

bash

# 2つのタグ間の差分
git diff v1.0.0 v1.1.0

# タグとHEADの差分
git diff v1.0.0 HEAD

# 統計情報
git diff v1.0.0 v1.1.0 --stat

タグ間のログを確認

bash

# タグ間のコミット履歴
git log v1.0.0..v1.1.0

# 1行表示
git log v1.0.0..v1.1.0 --oneline

# グラフ表示
git log v1.0.0..v1.1.0 --graph --oneline

タグからアーカイブを作成

bash

# zip形式
git archive --format=zip --output=v1.0.0.zip v1.0.0

# tar.gz形式
git archive --format=tar.gz --output=v1.0.0.tar.gz v1.0.0

# プレフィックス付き
git archive --format=tar.gz --prefix=project-v1.0.0/ --output=v1.0.0.tar.gz v1.0.0

バージョニング規則

セマンティックバージョニング

bash

# 形式: vMAJOR.MINOR.PATCH
git tag -a v1.0.0 -m "Initial release"          # メジャーリリース
git tag -a v1.1.0 -m "Add new features"         # マイナーリリース
git tag -a v1.1.1 -m "Bug fixes"                # パッチリリース

MAJOR: 互換性のない変更
MINOR: 後方互換性のある機能追加
PATCH: 後方互換性のあるバグ修正

プレリリースバージョン

bash

# ベータ版
git tag -a v2.0.0-beta.1 -m "Beta release 1"
git tag -a v2.0.0-beta.2 -m "Beta release 2"

# リリース候補
git tag -a v2.0.0-rc.1 -m "Release candidate 1"
git tag -a v2.0.0-rc.2 -m "Release candidate 2"

# アルファ版
git tag -a v2.0.0-alpha.1 -m "Alpha release"

ビルドメタデータ

bash

# ビルド番号付き
git tag -a v1.0.0+20250107 -m "Release with build metadata"
git tag -a v1.0.0+build.123 -m "Build 123"

実践的な使い方

リリースフロー

bash

# 1. developブランチで開発
git checkout develop
# 開発作業...

# 2. リリースブランチを作成
git checkout -b release/v1.0.0

# 3. バージョン番号を更新
vim package.json  # version: "1.0.0"
git add package.json
git commit -m "Bump version to 1.0.0"

# 4. mainにマージ
git checkout main
git merge release/v1.0.0

# 5. タグを作成
git tag -a v1.0.0 -m "Release version 1.0.0"

# 6. リモートにプッシュ
git push origin main
git push origin v1.0.0

# 7. developにもマージ
git checkout develop
git merge release/v1.0.0
git push origin develop

ホットフィックス

bash

# 1. タグからブランチを作成
git checkout -b hotfix/v1.0.1 v1.0.0

# 2. バグ修正
vim src/bug.js
git add src/bug.js
git commit -m "Fix critical bug"

# 3. バージョン番号を更新
vim package.json  # version: "1.0.1"
git add package.json
git commit -m "Bump version to 1.0.1"

# 4. mainにマージ
git checkout main
git merge hotfix/v1.0.1

# 5. タグを作成
git tag -a v1.0.1 -m "Hotfix release 1.0.1"

# 6. プッシュ
git push origin main
git push origin v1.0.1

# 7. developにもマージ
git checkout develop
git merge hotfix/v1.0.1
git push origin develop

タグの移行

bash

# 古いタグ形式から新しい形式へ

# 1. 古いタグを確認
git tag
# release-1.0
# release-1.1

# 2. 新しいタグを作成
git tag -a v1.0.0 release-1.0 -m "Version 1.0.0"
git tag -a v1.1.0 release-1.1 -m "Version 1.1.0"

# 3. 古いタグを削除
git tag -d release-1.0
git tag -d release-1.1

# 4. リモートを更新
git push origin v1.0.0 v1.1.0
git push origin --delete release-1.0
git push origin --delete release-1.1

タグの検索とフィルタリング

パターンマッチング

bash

# v1系のすべてのタグ
git tag -l "v1.*"

# ベータ版のみ
git tag -l "*beta*"

# パッチバージョンのみ（v1.0.x）
git tag -l "v1.0.*"

# 特定のプレフィックス
git tag -l "release-*"

日付でソート

bash

# 作成日順にソート
git tag --sort=creatordate

# 逆順
git tag --sort=-creatordate

# 最新のタグを表示
git tag --sort=-creatordate | head -1

バージョンでソート

bash

# バージョン順にソート
git tag --sort=version:refname

# 逆順
git tag --sort=-version:refname

よくあるパターン

パターン1: 最新のタグを取得

bash

# 最新のタグ
git describe --tags --abbrev=0

# または
git tag --sort=-version:refname | head -1

パターン2: 次のバージョン番号を決定

bash

# 現在のバージョンを確認
CURRENT=$(git describe --tags --abbrev=0)
echo "Current version: $CURRENT"

# 次のバージョンを手動で決定
# メジャー: v2.0.0
# マイナー: v1.1.0
# パッチ: v1.0.1

パターン3: リリースノート生成

bash

# 前回のタグから今回のタグまでのコミット
git log v1.0.0..v1.1.0 --oneline --no-merges

# リリースノートとして保存
git log v1.0.0..v1.1.0 --oneline --no-merges > RELEASE_NOTES.md

パターン4: タグの自動作成（CI/CD）

bash

# バージョンファイルから読み取り
VERSION=$(cat VERSION)
git tag -a "v$VERSION" -m "Release version $VERSION"
git push origin "v$VERSION"

よくあるエラーと対処

tag 'v1.0.0' already exists

bash

# エラー
fatal: tag 'v1.0.0' already exists

# 解決策1: 別の名前を使う
git tag -a v1.0.1 -m "New version"

# 解決策2: 強制的に上書き（非推奨）
git tag -f v1.0.0 -m "Updated tag"

# リモートも更新する場合
git push origin v1.0.0 --force

注意: 既存のタグを移動すると他の開発者に影響します。

! [rejected] v1.0.0 -> v1.0.0 (already exists)

bash

# エラー
 ! [rejected]        v1.0.0 -> v1.0.0 (already exists)

# 解決策: リモートのタグを削除してから再プッシュ
git push origin --delete v1.0.0
git push origin v1.0.0

# または強制プッシュ（非推奨）
git push origin v1.0.0 --force

タグがリモートにプッシュされない

bash

# タグを作成
git tag v1.0.0

# pushしたがタグが送信されない
git push origin main

# 解決策: タグを明示的にプッシュ
git push origin v1.0.0
# または
git push origin --tags

タグとブランチの違い

ブランチ

bash

# ブランチは移動する
git checkout feature
git commit -m "New commit"
# featureブランチが新しいコミットを指す

使い分け

ブランチ: 継続的な開発
タグ: 特定の時点のスナップショット（リリースなど）

GPG署名付きタグ

GPG鍵の設定

bash

# GPG鍵を生成
gpg --gen-key

# GPG鍵のIDを確認
gpg --list-keys

# Gitに設定
git config --global user.signingkey YOUR_GPG_KEY_ID

署名付きタグを作成

bash

# -sオプションで署名
git tag -s v1.0.0 -m "Signed release"

# 署名を検証
git tag -v v1.0.0

デフォルトで署名

bash

# タグ作成時に常に署名
git config --global tag.gpgSign true

ベストプラクティス

1. 注釈付きタグを使う

bash

# ❌ 軽量タグ
git tag v1.0.0

# ✅ 注釈付きタグ
git tag -a v1.0.0 -m "Release version 1.0.0"

2. セマンティックバージョニングに従う

bash

# vMAJOR.MINOR.PATCH
git tag -a v1.0.0 -m "Initial release"
git tag -a v1.1.0 -m "New features"
git tag -a v1.1.1 -m "Bug fixes"

3. わかりやすいメッセージを付ける

bash

# ❌ 不明瞭
git tag -a v1.0.0 -m "Release"

# ✅ 明確
git tag -a v1.0.0 -m "Release version 1.0.0 - Added user authentication and bug fixes"

4. タグを移動しない

bash

# ❌ タグを移動（混乱の原因）
git tag -f v1.0.0 new-commit

# ✅ 新しいタグを作成
git tag -a v1.0.1 -m "Updated release"

5. push --follow-tagsを使う

bash

# 注釈付きタグのみプッシュ
git push --follow-tags

# .gitconfigに設定
git config --global push.followTags true

よくある質問

Q: タグとブランチの違いは？

タグ: 固定、スナップショット、リリースに使用
ブランチ: 移動、開発に使用

Q: タグを削除しても大丈夫？

A: ローカルのタグは自由に削除できますが、リモートにプッシュ済みのタグは慎重に。他の人が使っている可能性があります。

Q: 軽量タグと注釈付きタグはどちらを使う？

A: リリースには必ず注釈付きタグを使います。軽量タグは一時的なマーカーのみに使用します。

Q: タグの命名規則は？

A: セマンティックバージョニング（vMAJOR.MINOR.PATCH）が推奨されます。

bash

v1.0.0, v1.1.0, v1.1.1, v2.0.0

Q: タグをチェックアウトするとdetached HEADになる？

A: はい。タグから作業する場合はブランチを作成します。

bash

git checkout -b hotfix-v1.0.0 v1.0.0

まとめ：覚えておくべきコマンド

タグの作成

bash

# 注釈付きタグ（推奨）
git tag -a v1.0.0 -m "Release version 1.0.0"

# 過去のコミットにタグ
git tag -a v0.9.0 a1b2c3d -m "Old release"

# GPG署名付き
git tag -s v1.0.0 -m "Signed release"

タグの表示

bash

# すべてのタグ
git tag

# パターンで絞り込み
git tag -l "v1.*"

# 詳細を表示
git show v1.0.0

タグの削除

bash

# ローカル
git tag -d v1.0.0

# リモート
git push origin --delete v1.0.0

タグのプッシュ

bash

# 特定のタグ
git push origin v1.0.0

# すべてのタグ
git push origin --tags

# 注釈付きタグのみ（推奨）
git push --follow-tags

タグの利用

bash

# チェックアウト
git checkout v1.0.0

# ブランチを作成
git checkout -b hotfix v1.0.0

# 差分を確認
git diff v1.0.0 v1.1.0

# ログを確認
git log v1.0.0..v1.1.0

タグは、リリース管理に欠かせない機能です。セマンティックバージョニングに従い、注釈付きタグを使うことで、プロジェクトのバージョン管理を明確にできます。