えっ、Git のタグって 2 種類!? 軽量 vs アノテートを5分で完全マスター

## 1. そもそもタグとは？

* **コミットに “人間が読める名前” を貼る機能**
* リリースバージョンやマイルストーンの目印として超便利！

## 2. 実は 2 タイプある

|                     | **軽量タグ (Lightweight)** |                              **アノテートタグ (Annotated)**                               |
| ------------------- | -------------------------- | ----------------------------------------------------------------------------------------- |
| 正体                | ただのポインタ             | `tag` オブジェクト                                                                        |
| メタデータ          | なし                       | 作成者・日付・メッセージ・GPG 署名                                                        |
| 作成コマンド        | `git tag v1.2.3`           | `git tag -a v1.2.3 -m "Release 1.2.3"`                                                    |
| 推奨用途            | **私的／一時的**           | **公式リリース**                                                                          |
| `git describe` 対象 | 無視される                 | デフォルトで採用 ([git-scm.com](https://git-scm.com/docs/git-tag?utm_source=chatgpt.com)) |

> Git 公式マニュアルも「軽量は private / temporary」と明言！

## 3. どう作る？

```bash
# 軽量：一瞬でペタッ
git tag test/v1.3.0

# アノテート：コメント付きでしっかり
git tag -a v1.3.0 -m "Release v1.3.0"
# 署名付きなら -s
git tag -s v1.3.0 -m "Signed release"
```

## 4. どう見る？

|    知りたい粒度    |           コマンド            |      見えるもの       |
| ------------------ | ----------------------------- | --------------------- |
| 一覧＋1行コメント  | `git tag -n` / `git tag -n99` | タグ名 + コメント先頭 |
| 詳細メタデータだけ | `git show --no-patch <tag>`   | タグ情報＋署名        |
| 生オブジェクト     | `git cat-file -p <tag>`       | raw tag オブジェクト  |

## 5. コマンド別「見えるタグ」早見表（事故防止の早見表）

|      コマンド & 典型例       | デフォルトで見えるのは？ |     オプションで切替     |                                                                      注意ポイント                                                                      |
| ---------------------------- | ------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `git describe`               | **Annotatedのみ**        | `--tags` で両方          | CI で多用。軽量タグは無視され事故りがち ([git-scm.com](https://git-scm.com/docs/git-tag?utm_source=chatgpt.com))                                       |
| `git log --decorate --tags`  | 両方                     | `--no-decorate` で非表示 | 見えても describe には採用されないケースあり                                                                                                           |
| `git for-each-ref refs/tags` | 両方                     | `--format` で柔軟表示    | 軽量タグは「作成日時」が無いので並び順に注意                                                                                                           |
| `git push --follow-tags`     | **Annotatedのみ**        | `--tags` で全部          | 自動 push では軽量タグが送られず「タグが無い！」事故が起きる ([git-scm.com](https://git-scm.com/book/en/v2/Git-Basics-Tagging?utm_source=chatgpt.com)) |
| `git show <tag>`             | 指定したタグそのもの     | —                        | 軽量タグを指定すると diff だけでメッセージが無いことですぐ分かる                                                                                       |

> 🔔 **覚えておくべき 2 つの罠**
>
> 1. **describe ＝リリース判定ロジック** に軽量タグは反映されない。
> 2. **push --follow-tags は Annotated だけ**。軽量を使うなら `--tags` で明示！

## 6. 迷ったらこう覚えよう！

> **「公開するならアノテート、一時的なローカル用途は軽量」**

* CI/CD・GitHub Release・`git describe` ＝ **アノテート前提**
* 軽量で付けた後「やっぱ正式リリース！」と思ったら

  ```bash
  git tag -d v1.3.0
  git tag -a v1.3.0 -m "Release v1.3.0"
  ```

## 7. まとめ

1. **タグは2種類。軽量＝ただのしおり、アノテート＝履歴付きしおり。**
2. **公式も「軽量は私的／一時的」と明言。** ([git-scm.com](https://git-scm.com/docs/git-tag))
3. **リリース・自動化・チーム共有なら迷わずアノテート！** 🚀