タグでリリースに印をつける

「あのとき出したやつ」を、ハッシュでは呼べない

ブランチは、新しいコミットを作るたびに先端が前へ進みます。タグは逆です。あるコミットに名前をつけたら、そのあと何回コミットしても最初のコミットを指し続けます。動かない目印です。

これが効くのはリリースの瞬間を残したいときです。バグ報告を受けたときに、報告者のバージョンのコードをそのまま手元に再現できます。ハッシュでも同じことはできますが、「v1.2.0 で入ったバグ」と言えば全員に通じるのに対し、「9f3c1a2 で入ったバグ」と言われて分かる人はいません。

$ git tag -a v1.0.0 -m "初回リリース"
$ git tag
v0.1.0
v1.0.0

自分用の目印と、公開するリリースは別物

git tag v0.1.0 のように -a を付けずに作ったものは軽量タグと呼ばれ、中身はコミットのハッシュを書いただけのファイルです。

-a と -m を付けた注釈付きタグは、コミットと同じく独立したオブジェクトとして保存され、作成者の名前とメールアドレス、作成日時、メッセージが入ります。違いは git show に出ます。

$ git show v1.0.0
tag v1.0.0
Tagger: Taro Yamada <taro@example.com>
Date:   Mon Mar 3 10:12:44 2025 +0900

初回リリース

軽量タグではこの 5 行が出ず、いきなりコミットの情報から始まります。公開するリリースには注釈付きタグを使ってください。 半年後に「このバージョンは誰がいつ出したのか」を調べる場面が必ず来ます。そのとき軽量タグには、何の手がかりも残っていません。

v1.2.3 の数字が読めないと、上げる番号を間違える

多くのプロジェクトは、セマンティックバージョニングという共通の決まりに従っています。

v1.2.3 から進む例で見ます。ボタンの色を直すバグ修正だけなら v1.2.4。検索機能を足したが既存の画面はそのまま動くなら v1.3.0。設定ファイルの書式を変えて古い設定では起動しないなら v2.0.0 です。メジャーが上がるときは右の数字がゼロに戻るので、v1.3.0 の次は v2.3.0 ではなく v2.0.0 になります。

この決まりが効くのは、他人のライブラリを使うときです。v1.2.9 への更新は安心して当てられるが、v2.0.0 は自分のコードを直す必要があるかもしれない。番号だけでそこまで判断できます。

タグを打ったのに、GitHub に出てこない

ここがいちばんの落とし穴です。タグは git push では送られません。 ブランチのコミットだけが送られ、タグは手元に残ります。

「タグを作ったのに消えた」と思ったら、リモート側を見てください。

$ git ls-remote --tags origin
9f3c1a2f8e6d5c4b3a2918f7e6d5c4b3a2918f7e	refs/tags/v0.1.0
$ git push origin v1.0.0
 * [new tag]         v1.0.0 -> v1.0.0

GitHub の Releases に並んでいるのは、実はタグそのものです。「Releases に出てこない」という相談のほとんどは、この push 忘れです。

なお、タグを打つ前に git switch main と git pull で手元を最新にします。古いまま打つと、リリースしたつもりのないコミットに v1.2.0 がついてしまいます。