git tag と npm dist-tag は別物です
とあるドキュメントを読む中で git tag と npm dist-tag が共にタグという表現がされており混乱する場面がありました。同じタグでも役割が全く違うものなので、それぞれのタグが何かについてこの記事では説明します。
主に npm パッケージ開発をしている人に役立つ内容になると嬉しいです。
結論、何のためのタグなのか？
git tag はコミット履歴上の特定ポイントにマーキングするための仕組みで、主にリリースバージョンの記録に使用され、そのコミットに簡単にアクセスできるようにします。
npm dist-tag はパッケージの特定バージョンにラベルを付けるための仕組みで、インストール時に利用者が適切なバージョン（安定版や開発版など）を選択できるようにします。
各タグの詳細についてはこの後説明します。
git tag
git tag とは コミット履歴上の特定のポイントにマーキングするため仕組み です。
よくあるのは、リリースバージョン（例: v1.0.0）を記録するために使用されます。これにより、バージョン更新時のコミットを特定することが容易になります。
タグ名はセマンティックバージョンのプレフィックスに v をつけることが一般的です。
タグの種類
git tag は以下の 2 種類があります。
- 軽量タグ：単純なコミットへの参照
- 注釈付きタグ：タグを作成した人の名前・メールアドレス・作成日時・メッセージなどの追加情報を含む
軽量タグは特定のコミットを示す単なる印です。
一方で、注釈付きタグはオブジェクトとして追加情報を渡すことができます。
一般的には注釈付きタグの利用が推奨されています。
よく使うコマンド
# タグ一覧の表示
git tag
# 新しいタグを作成（軽量タグ）
git tag v1.0.0
# 注釈付きタグを作成
git tag -a v1.0.0 -m "バージョン1.0.0をリリース"
# タグをリモートにプッシュ
git push origin v1.0.0
# すべてのタグをプッシュ
git push origin --tags
# ローカルタグの削除
git tag -d v1.0.0
# リモートタグの削除
git push origin --delete v1.0.0
# 注釈付きタグの情報を確認
git show v1.0.0
また、パッケージのバージョンを更新する npm version コマンド（例: npm version patch）を実行時も注釈付きの git tag が発行されます。
git tag はスイッチすることが可能です。
バージョンと git tag を紐付けしていた場合、用意に特定のバージョンのリリースコミットへ移動することができます。
# v1.0.0 タグが指すコミットに移動する
git switch v1.0.0
npm dist-tag
npm dist-tag とは npm パッケージの特定バージョンに対するラベル付けの仕組みです。
これを使うことで、安定版と開発版の区別（latest, beta, next など）を行うことができ、 npm install 時にデフォルトで最新のパッケージ（latest）をインストールしてきたり、dist-tag を指定して npm install することで beta 版等のインストールが可能になります。
特別な dist-tag
latest タグだけ特別な dist-tag で npm install パッケージ名 でパッケージをインストールした際にこのタグに紐づいたパッケージをインストールします。
よく使うコマンド
# タグ一覧の表示
npm dist-tag ls [パッケージ名]
# 新しいタグを追加
npm dist-tag add パッケージ名@バージョン タグ名
# タグを削除
npm dist-tag rm パッケージ名 タグ名
# 特定のタグでインストール
npm install パッケージ名@ タグ名
dist-tag に紐づいたパッケージの公開は以下のように実施可能です。
# ベータ版のパブリッシュ（beta タグを付与）
npm publish --tag beta
# リリース版のパブリッシュ（デフォルトで latest タグが付与される）
npm publish
実際の使用例
TypeScript のリポジトリをクローンして npm dist-tag ls を実行してみます。
$ npm dist-tag ls
beta: 5.8.0-beta
dev: 3.9.4
insiders: 4.6.2-insiders.20220225
latest: 5.8.2
next: 5.9.0-dev.20250328
rc: 5.8.1-rc
tag-for-publishing-older-releases: 4.1.6
latest 以外に beta, next など様々な dist-tag がそれぞれバージョンに紐付けされていることが分かります。
TypeScript リポジトリの README > Installing を見てみると
latest は dist-tag 指定なしで、 next は dist-tag を指定すると最新のビルドバージョンがインストール可能なことが分かります。
まとめ
この記事では、git tag と npm dist-tag の違いについて解説しました。
npm パッケージ開発では、これらを併用することが一般的です。git tag でリポジトリ上の各リリースポイントを記録し、npm dist-tag でパッケージレジストリ上での各バージョンの役割を明確にします。これにより、開発者はパッケージの変更履歴を容易に追跡でき、利用者は自分のニーズに合ったバージョンを簡単に選択できるようになります。
両者は名前に「タグ」という言葉を含みますが、目的も実装も全く異なるものであることを理解しておくと、npm パッケージ開発がよりスムーズになると思います。
Discussion