Git 標籤 (Tag)

Tag 用來標記特定的 commit，通常用於標記版本發布點，例如 v1.0.0、v2.1.3。

標籤的類型

Git 有兩種標籤：

Lightweight Tag（輕量標籤）

只是一個指向 commit 的指標，沒有額外資訊：

git tag v1.0.0

Annotated Tag（註解標籤）

包含作者、日期、訊息等資訊，建議用於正式的版本發布：

git tag -a v1.0.0 -m "Version 1.0.0 release"

建立標籤

建立輕量標籤

# 標記當前 commit
git tag v1.0.0

# 標記特定 commit
git tag v1.0.0 a1b2c3d

建立註解標籤

# 會開啟編輯器輸入訊息
git tag -a v1.0.0

# 直接指定訊息
git tag -a v1.0.0 -m "First stable release"

# 標記特定 commit
git tag -a v1.0.0 a1b2c3d -m "Version 1.0.0"

簽署標籤（GPG）

git tag -s v1.0.0 -m "Signed release"

查看標籤

列出所有標籤

git tag

輸出：

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

篩選標籤

# 列出 v1 開頭的標籤
git tag -l "v1.*"

# 列出包含 beta 的標籤
git tag -l "*beta*"

查看標籤資訊

# 查看標籤指向的 commit
git show v1.0.0

對於註解標籤，會顯示：

  • 標籤作者
  • 標籤日期
  • 標籤訊息
  • 對應的 commit 資訊

依照版本排序

git tag --sort=version:refname
git tag --sort=-version:refname  # 反向排序

推送標籤到遠端

標籤預設不會被 git push 推送。

推送單一標籤

git push origin v1.0.0

推送所有標籤

git push origin --tags

只推送註解標籤

git push origin --follow-tags

刪除標籤

刪除本地標籤

git tag -d v1.0.0

刪除遠端標籤

git push origin --delete v1.0.0
# 或
git push origin :refs/tags/v1.0.0

切換到標籤

git checkout v1.0.0

這會進入 detached HEAD 狀態。如果需要在這個版本上開發，建議建立分支：

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

版本號命名慣例

Semantic Versioning（語意化版本）

最常見的版本命名方式：MAJOR.MINOR.PATCH

  • MAJOR：不相容的 API 變更
  • MINOR：新增功能（向下相容）
  • PATCH：Bug 修復（向下相容）

例如：

  • v1.0.0：第一個正式版
  • v1.1.0：新增功能
  • v1.1.1：Bug 修復
  • v2.0.0：重大變更

Pre-release 版本

v1.0.0-alpha.1
v1.0.0-beta.1
v1.0.0-rc.1
v1.0.0

實際範例

發布新版本

# 1. 確保在 main 分支且是最新
git checkout main
git pull

# 2. 建立版本標籤
git tag -a v1.2.0 -m "Release version 1.2.0

Features:
- Add user authentication
- Improve performance

Bug fixes:
- Fix login timeout issue"

# 3. 推送標籤
git push origin v1.2.0

補打標籤

忘記打標籤？可以補打：

# 找到對應的 commit
git log --oneline

# 在那個 commit 上打標籤
git tag -a v1.0.0 a1b2c3d -m "Version 1.0.0 (retrospective tag)"
git push origin v1.0.0

修正錯誤的標籤

# 刪除錯誤的標籤
git tag -d v1.0.0
git push origin --delete v1.0.0

# 重新建立正確的標籤
git tag -a v1.0.0 <correct-commit> -m "Correct version 1.0.0"
git push origin v1.0.0

比較兩個版本

# 兩個版本之間的 commit
git log v1.0.0..v2.0.0 --oneline

# 兩個版本的差異
git diff v1.0.0 v2.0.0

# 變更的檔案列表
git diff v1.0.0 v2.0.0 --stat

Tag vs Branch

TagBranch
用途標記特定時間點持續開發
是否移動不會（固定指向某個 commit）會隨著新 commit 移動
適用情境版本發布功能開發

搭配 GitHub Releases

GitHub 的 Release 功能是建立在 tag 之上的：

  1. 建立標籤並推送
  2. 在 GitHub 點擊 Releases → Draft a new release
  3. 選擇標籤
  4. 填寫 Release notes
  5. 可以附加檔案（如編譯好的程式）

或者使用 GitHub CLI：

gh release create v1.0.0 --title "Version 1.0.0" --notes "Release notes here"

自動化標籤

用 npm version（Node.js 專案）

npm version patch  # 1.0.0 → 1.0.1
npm version minor  # 1.0.0 → 1.1.0
npm version major  # 1.0.0 → 2.0.0

這會自動更新 package.json 的版本並建立 git tag。

搭配 CI/CD

在 GitHub Actions 中根據 tag 觸發部署：

on:
  push:
    tags:
      - 'v*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Deploying version ${{ github.ref_name }}"