Gitのタグの使い方とバージョン番号の付け方:セマンティックバージョニングも解説
アプリを公開したとき、「このコミットがバージョン 1.0.0」と目印を付けておくのが Git のタグです。あとから「1.0.0 のときのコードを見たい」「1.0.0 から何コミット進んだか知りたい」というときに、コミット ID(7957d3f のような英数字)を探さずに名前で呼び出せます。
この記事では、タグの付け方・一覧・push・削除・付け直しの注意と、タグ名に使うバージョン番号の決め方(セマンティック バージョニング)を説明します。コマンドと実行結果は、Windows 11 の Git Bash(Git 2.49.0)で練習用のリポジトリとリモート(自分の PC の中に作ったもの)を使って確かめました。コミット ID と日時は、実行するたびに違う値になります。
この記事で使うコマンド
| やりたいこと | コマンド |
|---|---|
| 注釈付きタグを付ける | git tag -a v1.0.0 -m “メッセージ” |
| 過去のコミットに付ける | git tag -a v0.1.0 -m “メッセージ” コミットID |
| 一覧を見る(絞り込み) | git tag -l “v1.*” |
| バージョン順に並べる | git tag -l –sort=-v:refname |
| タグの中身を見る | git show v1.0.0 |
| 1 つ送る | git push origin v1.0.0 |
| コミットと一緒に注釈付きタグを送る | git push –follow-tags |
| 手元のタグを消す | git tag -d v1.0.0 |
| リモートのタグを消す | git push origin –delete v1.0.0 |
| 今がどのタグから何コミット目か | git describe |
タグとは?ブランチとの違い
タグは、特定のコミットに付ける「名札」です。ブランチも名札の一種ですが、ブランチはコミットするたびに新しいコミットへ進むのに対して、タグは付けたコミットから動きません。そのため「リリースした時点」を記録するのに向いています。
タグには 2 種類あります。
| 注釈付きタグ(annotated) | 軽量タグ(lightweight) | |
|---|---|---|
| 付け方 | git tag -a 名前 -m “メッセージ” | git tag 名前 |
| 記録されるもの | 付けた人・日時・メッセージ | 指しているコミットだけ |
| git describe | 使われる | そのままでは使われない(–tags が必要) |
| git push –follow-tags | 送られる | 送られない |
| 向いている用途 | リリース | 自分用・一時的な目印 |
Git の公式ドキュメント(git-tag)には「注釈付きタグはリリース用、軽量タグは自分用や一時的な目印用」と書かれていて、公式の解説書(Pro Git)でも、情報がすべて残る注釈付きタグを使うことが一般的にすすめられています。リリースには注釈付きタグと覚えておけば十分です。
バージョン番号の決まり:セマンティック バージョニング
タグの名前には v1.2.3 のようなバージョン番号がよく使われます。この番号の付け方として広く使われているのがセマンティック バージョニング(Semantic Versioning、略して SemVer)です。semantic は「意味のある」という意味で、番号のどこが上がったかで「何が変わったか」が分かるようにする決まりです。ここでは公式サイト semver.org の 2.0.0 の原文に沿って説明します。
MAJOR.MINOR.PATCH の上げ方
バージョン番号は「MAJOR.MINOR.PATCH」(メジャー・マイナー・パッチ)の 3 つの数字です。どれも 0 以上の整数で、01 のような先頭の 0 は付けません。
| 上げる数字 | 上げるとき | 例(1.4.2 から) |
|---|---|---|
| MAJOR | 今までの使い方ができなくなる変更(互換性のない変更) | 2.0.0 |
| MINOR | 今までの使い方のまま、機能を追加したとき | 1.5.0 |
| PATCH | 今までの使い方のまま、バグを直したとき | 1.4.3 |
ポイントは 2 つです。
- 上の桁を上げたら、下の桁は 0 に戻す:1.4.2 で機能を追加したら 1.5.0(1.5.2 ではない)。互換性のない変更なら 2.0.0
- 各桁は数値として増やす:1.9.0 の次のマイナーは 1.10.0。「10」は小数ではなく整数なので、1.10.0 は 1.9.0 より新しい
ここでいう「使い方」とは、そのソフトウェアが外向けに約束している使い方(公開 API。関数の名前と引数、コマンドのオプションなど)のことです。SemVer では、最初にこの公開 API をはっきりさせることが求められています。また、一度リリースしたバージョンの中身は変えてはいけない(直すなら新しいバージョンとして出す)とも定められています。これはタグの付け直しの話にもつながります。
0.y.z は「開発中」、1.0.0 から正式
MAJOR が 0 のバージョン(0.1.0 や 0.12.3 など)は初期の開発用で、「いつ何が変わってもよい」とされています。0.y.z を使っているソフトウェアは、MINOR が上がっただけでも使い方が変わるかもしれない、と考えておく必要があります。
semver.org のよくある質問では、最初のリリースは 0.1.0 から始め、その後はリリースごとに MINOR を上げるのが簡単だとしています。そして「本番環境で使われているなら、たぶんもう 1.0.0 にすべき」「利用者が頼りにしている安定した API があるなら 1.0.0 にすべき」と書かれています。1.0.0 は「公開 API が決まった」という宣言です。
プレリリース(-alpha.1)とビルドメタデータ(+)
正式版の前に試してもらう版は、PATCH のあとにハイフンと識別子を付けて表します(プレリリース)。識別子はドットで区切ります。使える文字は半角英数字とハイフンだけです。
2.0.0-alpha.1 アルファ版の 1 つ目
2.0.0-beta.2 ベータ版の 2 つ目
2.0.0-rc.1 リリース候補(release candidate)の 1 つ目
2.0.0 正式版
プレリリースは、同じ番号の正式版より前(古い)と扱われます。つまり 2.0.0-rc.1 は 2.0.0 より前です。また、プレリリースは「まだ不安定で、2.0.0 として約束する互換性を満たさないかもしれない版」という意味になります。
プラス記号のあとにはビルドメタデータ(ビルドの日時やコミット ID などの付加情報)を書けます。例:1.0.0+20130313144700、1.0.0-beta+exp.sha.5114f85。ビルドメタデータは順番の比較では無視されるので、1.0.0+001 と 1.0.0+002 は同じ順位です。
どちらが新しい?順番の比べ方
比べ方は、MAJOR → MINOR → PATCH の順に数値として比べます。同じなら、プレリリースのない方が新しく、プレリリースどうしはドットで区切った部分を左から比べます(数字だけの部分は数値で、文字を含む部分は ASCII の文字順で比べ、数字だけの部分は文字を含む部分より前)。semver.org に載っている例は次のとおりです。
1.0.0 < 2.0.0 < 2.1.0 < 2.1.1
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta
< 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0
beta.2 < beta.11 になっているのは、2 と 11 を数値で比べるからです。文字として比べると「1」が「2」より前なので逆になってしまいます。この違いは、あとで紹介する git tag の並び順でも問題になります。
「v」を付ける?付けない?
semver.org のよくある質問には「v1.2.3 はセマンティック バージョンか?」という項目があり、答えは「いいえ」です。バージョン番号そのものは 1.2.3 で、Git のタグ名などで先頭に v を付けるのはよくある慣習だと説明されています。つまり、タグ名は v1.2.3 でも 1.2.3 でもかまいません。大事なのはプロジェクトの中でそろえることです。この記事では v を付けた形で進めます。
Python のパッケージのバージョンは少し書き方が違う
Python のパッケージ(pip でインストールするもの)のバージョンは、Python Packaging の公式仕様「Version specifiers」(元は PEP 440)に従います。MAJOR.MINOR.PATCH の部分は SemVer と同じ考え方で使えますが、プレリリースは 1.0.0a1、1.0.0b1、1.0.0rc1 のようにハイフンなしで書くのが正式な形です。仕様には、ハイフン付きの SemVer のプレリリースや「+」のビルド情報はそのままでは互換性がない、と書かれています(先頭の v は無視される、という決まりもあります)。
準備:練習用のリポジトリ
「Git入門:初期設定から最初のコミットまで」と同じように hello.py を作り、コミットが 2 つあり、リモート(origin)に push 済みの状態から始めます。
7957d3f Gitと表示する処理を追加
292bbe1 最初のコミット
注釈付きタグを付ける(git tag -a)
今のコミット(HEAD)を最初の正式リリース v1.0.0 にします。-a が注釈付き、-m のあとがメッセージです。
git tag -a v1.0.0 -m "最初の正式リリース"
成功しても何も表示されません。git tag とだけ実行すると、タグの一覧に v1.0.0 と表示されます。なお、公式ドキュメントによると -m を付けると -a を省略しても注釈付きになりますが、意図が分かるように -a も書いておくのがおすすめです。-m も省略すると、メッセージを書くためのエディターが開きます。
軽量タグとの違いを確かめる
比べるために、同じコミットに軽量タグも付けてみます。
git tag v1.0.0-light
git cat-file -t で、それぞれのタグ名が何を指しているか(オブジェクトの種類)を調べます。
git cat-file -t v1.0.0
結果は tag、git cat-file -t v1.0.0-light の結果は commit でした。注釈付きタグは「タグオブジェクト」という独立したデータ(付けた人・日時・メッセージを持つ)として保存され、軽量タグはコミットを直接指す名前だけ、ということが分かります。確かめたら軽量タグは消しておきます。
git tag -d v1.0.0-light
Deleted tag 'v1.0.0-light' (was 7957d3f)
タグの中身を見る(git show)
git show v1.0.0
tag v1.0.0
Tagger: Taro <taro@example.com>
Date: Sun Oct 18 19:23:33 2026 +0900
最初の正式リリース
commit 7957d3f89052965c42fe1e4985996c01060b0a15
Author: Taro <taro@example.com>
Date: Sun Oct 18 19:23:33 2026 +0900
Gitと表示する処理を追加
(このあとにコミットの差分が続く)
上の 4 行がタグの情報(Tagger=タグを付けた人、日時、メッセージ)、その下がタグの付いたコミットです。軽量タグで git show を実行すると、タグの情報はなく、いきなり commit の行から表示されます。
過去のコミットにタグを付ける
タグ名のあとにコミット ID(またはブランチ名や HEAD~1 など)を書くと、そのコミットにタグを付けられます。「最初のコミット」(292bbe1)を試作版の v0.1.0 にしてみます。
git tag -a v0.1.0 -m "試作版" 292bbe1
git log --oneline --decorate で、どのコミットにタグが付いているかが分かります。
7957d3f (HEAD -> main, tag: v1.0.0, origin/main) Gitと表示する処理を追加
292bbe1 (tag: v0.1.0) 最初のコミット
タグの一覧を見る・絞り込む(git tag -l)
タグが増えてきたリポジトリで git tag を実行すると、次のように表示されました。
v0.1.0
v1.0.0
v1.1.0
v1.10.0
v1.2.0
v1.9.0
v2.0.0
v2.0.0-alpha.1
v2.0.0-rc.1
何も指定しないと文字の順に並ぶため、v1.10.0 が v1.2.0 より前に来てしまいます。-l(--list)のあとにパターンを書くと絞り込めます。* は「任意の文字列」という意味です。
git tag -l "v1.*"
v1.0.0
v1.1.0
v1.10.0
v1.2.0
v1.9.0
バージョンとして正しく並べたいときは --sort=v:refname を使います。先頭に - を付けると新しい順(降順)です。
git tag -l --sort=-v:refname
v2.0.0-rc.1
v2.0.0-alpha.1
v2.0.0
v1.10.0
v1.9.0
v1.2.0
v1.1.0
v1.0.0
v0.1.0
1.10.0 と 1.9.0 は正しく並びましたが、v2.0.0-rc.1 が v2.0.0 より新しい扱いになっています。Git の標準の並べ方は SemVer のプレリリースのルールとは違うためです。設定 versionsort.suffix に「-」を指定すると、ハイフンの付いたものが正式版より前に並びました(git -c versionsort.suffix=- tag -l --sort=-v:refname で、v2.0.0 → v2.0.0-rc.1 → v2.0.0-alpha.1 の順)。
メッセージも一緒に見たいときは git tag -n です。注釈付きタグはタグのメッセージ、軽量タグはコミットのメッセージの 1 行目が表示されます。
タグをリモートに送る(push)
ここが一番つまずきやすい点です。普通の git push ではタグは送られません。注釈付きタグを付けてから git push -u origin main を実行し、git ls-remote --tags origin(リモートにあるタグの一覧)で確かめたところ、何も表示されませんでした。タグは別に送る必要があります。
1 つだけ送る
git push origin v1.0.0
To ../origin.git
* [new tag] v1.0.0 -> v1.0.0
コミットと一緒に注釈付きタグを送る(–follow-tags)
機能を 2 つ追加してコミットし、注釈付きタグ v1.1.0 と、自分用の軽量タグ test-build を付けた状態で、--follow-tags を付けて push してみます。
git push --follow-tags
To ../origin.git
7957d3f..bda04d6 main -> main
* [new tag] v0.1.0 -> v0.1.0
* [new tag] v1.1.0 -> v1.1.0
main と一緒に、まだ送っていなかった注釈付きタグ(v0.1.0 と v1.1.0)だけが送られ、軽量タグ test-build は送られませんでした。公式ドキュメントでも、–follow-tags は「送るコミットからたどれる注釈付きタグのうち、リモートにないもの」を一緒に送る、と説明されています。毎回付けるのが面倒なら、git config --global push.followTags true で標準にできます。
すべてのタグを送る(–tags)
git push origin --tags
To ../origin.git
* [new tag] test-build -> test-build
--tags は軽量タグも含めて手元のタグを全部送ります。自分用の目印まで共有されてしまうので、ふだんは 1 つずつ送るか --follow-tags を使う方が安全です。
タグを削除する(手元・リモート)
間違って送った test-build を消します。git tag -d で消えるのは手元のタグだけで、リモートのタグは残ります。リモートは別に消します。
git tag -d test-build
git push origin --delete test-build
To ../origin.git
- [deleted] test-build
同じ名前のブランチもある場合は、git push origin --delete refs/tags/test-build のように refs/tags/ を付けるとタグだと明示できます。ただし、ほかの人がすでに取得(fetch)したタグは、その人の PC には残ります。
タグを付け直すときの注意
v1.1.0 を送ったあとで、直し忘れに気付いて修正をコミットしたとします。同じ名前でタグを付けようとするとエラーになります。
fatal: tag 'v1.1.0' already exists
-f(force)を付けると手元では付け直せますが、push すると断られます。
! [rejected] v1.1.0 -> v1.1.0 (already exists)
error: failed to push some refs to '../origin.git'
hint: Updates were rejected because the tag already exists in the remote.
git push -f origin v1.1.0 で無理に上書きすることはできます。しかし、上書きする前にリポジトリを取得していた別の PC で git fetch --tags を実行すると、次のように断られ、古い v1.1.0 のままでした。
! [rejected] v1.1.0 -> v1.1.0 (would clobber existing tag)
「would clobber existing tag」は「今あるタグを上書きしてしまう」という意味です。Git は、ほかの人の手元にあるタグを勝手に書き換えません。その結果、人によって「v1.1.0」の中身が違う、という状態になります。git-tag の公式ドキュメントの「On Re-tagging」でも、正しいやり方は「間違いを認めて別の名前にすること」とされています。SemVer でも、リリースしたバージョンの中身は変えず、新しいバージョンとして出すことになっています。
送ったタグは付け直さず、修正は v1.1.1 として出すのが基本です。-f での付け直しは、まだ誰にも送っていないタグだけにしましょう。
今がどのバージョンから何コミット目か(git describe)
git describe は、今のコミットからさかのぼって一番近いタグを探し、そこから何コミット進んでいるかを表示します。v1.0.0 のあとに 2 つコミットした状態で実行しました。
git describe
v1.0.0-2-gbda04d6
「v1.0.0 から 2 コミット進んだ、コミット bda04d6」という意味です。g は Git の頭文字で、ID の一部ではありません。タグの付いたコミットそのものなら v1.0.0 だけが表示されます。主な使い方は次のとおりです。
| コマンド | 実行結果の例 | 意味 |
|---|---|---|
| git describe –abbrev=0 | v1.0.0 | 一番近いタグ名だけ |
| git describe –tags | v0.1.0-1-g0576fae | 軽量タグも対象にする |
| git describe –tags –dirty | v0.1.0-1-g0576fae-dirty | 未コミットの変更があれば -dirty を付ける |
| git describe –always | 8c60987 | タグがなければコミット ID を出す |
注釈付きタグがなく、軽量タグだけのリポジトリで git describe を実行すると、次のエラーになりました。軽量タグを「自分用」として扱う、という Git の考え方が表れています。
fatal: No annotated tags can describe '0576fae6470ba6b8b4bdf4bd26af59a5232e0f00'.
However, there were unannotated tags: try --tags.
タグが 1 つもないときは fatal: No names found, cannot describe anything. です。
タグの時点のコードを見る(detached HEAD)
v1.0.0 のときのファイルを見たいときは、タグ名で切り替えます。
git checkout v1.0.0
Note: switching to 'v1.0.0'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
(中略)
HEAD is now at 7957d3f Gitと表示する処理を追加
detached HEAD(デタッチド ヘッド)は「どのブランチにもいない状態」です。見るだけなら問題ありませんが、この状態でコミットしてもどのブランチにも入らず、ブランチに戻ると見失いやすくなります。見終わったら git switch main で戻ります。
git switch v1.0.0 とすると fatal: a branch is expected, got tag 'v1.0.0' と断られます。switch では git switch --detach v1.0.0 と書きます。
古いバージョンのバグを直したい(v1.0.1 を作りたい)ときは、タグの位置からブランチを作って作業します。
git switch -c hotfix-1.0.1 v1.0.0
Switched to a new branch 'hotfix-1.0.1' と表示され、ブランチの上で作業できます。ブランチについては「Gitのブランチの使い方」で詳しく説明しています。
よくある間違い
| 困ったこと | 原因 | 対処 |
|---|---|---|
| GitHub などにタグが出てこない | git push だけではタグは送られない | git push origin タグ名 か –follow-tags |
| git describe がエラーになる | 軽量タグしかない | 注釈付きタグを付ける。または –tags |
| git tag “v1.*” でエラー | -l がないと「v1.*」という名前のタグを作ろうとする | git tag -l “v1.*” |
| v1.10.0 が v1.2.0 より前に並ぶ | 文字の順で並べている | –sort=-v:refname |
| 消したはずのタグが他の人の PC に残る | 取得済みのタグは消えない | 本人に git tag -d してもらう |
| 1.4.2 に機能を足して 1.5.2 にした | 下の桁を 0 に戻していない | 1.5.0 にする |
3 行目は実際に試すと fatal: 'v1.*' is not a valid tag name. と表示されました。目的のコマンドが思い出せないときは「Git コマンド検索」で「タグ」と入れると、タグ関係のコマンドをまとめて探せます。
よくある質問
Q. 互換性のない変更をうっかり MINOR で出してしまったら?
semver.org のよくある質問では、気付いた時点で直し、互換性を元に戻した新しい MINOR バージョンを出すこととされています。その場合でも、リリース済みのバージョンを書き換えるのは「許されない」とはっきり書かれています。問題のあったバージョンのことは利用者に知らせましょう。
Q. タグ名に日本語や空白は使える?
試したところ、日本語のタグ名は作れましたが、空白を含む "v 1" は fatal: 'v 1' is not a valid tag name. と断られました(v1.* が断られたのも、* が使えない文字だからです)。ほかのツールとの相性を考えると、半角英数字・ドット・ハイフンだけにしておくのが無難です。
Q. ブランチ名と同じ名前のタグを作ってもいい?
作れてしまいますが、その名前を使うたびに warning: refname 'same' is ambiguous.(名前があいまい)という警告が出て(same という名前で試した場合)、どちらを指しているのか分かりにくくなります。タグは v1.0.0、ブランチは hotfix-1.0.1 のように、見て区別できる名前にしましょう。
まとめ
- リリースには注釈付きタグ(
git tag -a v1.0.0 -m "...") - タグは git push だけでは送られない。
git push origin v1.0.0か--follow-tags - 送ったタグは付け直さず、新しいバージョンを出す
- 番号は MAJOR(互換性のない変更)・MINOR(機能追加)・PATCH(バグ修正)。上を上げたら下は 0、開発中は 0.y.z
関連する記事・ツール
- Gitコマンド検索
- Git入門:インストール後の初期設定から最初のコミットまでを実行結果つきで解説
- Gitのブランチの使い方:作成・切り替え・マージ・削除を実行結果つきで解説
- Gitで取り消す方法まとめ:restore・reset・revertの使い分けを解説
- git rebaseの使い方とmergeとの違い:rebase -iと戻し方も解説
- Gitの履歴を調べる方法:git logの絞り込み・blame・bisectを実例で解説
- Gitのリモートの基本:fetch・pull・pushの違いを実行結果つきで解説