English ▾ 主題 ▾ 最新版本 ▾ git-tag 最後更新於 2.55.0

名稱

git-tag - 建立、列出、刪除或驗證標籤（tag）

概要

git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
	[(--trailer <token>[(=|:)<value>])…​]
	<tagname> [<commit> | <object>]
git tag -d <tagname>…​
git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
	[--points-at <object>] [--column[=<options>] | --no-column]
	[--create-reflog] [--sort=<key>] [--format=<format>]
	[--merged <commit>] [--no-merged <commit>] [<pattern>…​]
git tag -v [--format=<format>] <tagname>…​

描述

在 refs/tags/ 中新增一個標籤參照，除非使用 -d/-l/-v 來刪除、列出或驗證標籤。

除非指定了 -f，否則所命名的標籤必須尚未存在。

如果傳入了 -a、-s 或 -u <key-id> 其中之一，該指令將會建立一個標籤（tag）物件，並需要一個標籤訊息。除非指定了 -m <msg> 或 -F <file>，否則將會啟動編輯器讓使用者輸入標籤訊息。

如果指定了 -m <msg> 或 -F <file> 或 --trailer <token>[=<value>]，而未指定 -a、-s 和 -u <key-id>，則隱含 -a。

否則，將會建立一個直接指向給定物件的標籤參照（即輕量標籤）。

當使用 -s 或 -u <key-id> 時，將會建立一個經密碼學簽署的標籤物件。簽署後端（GPG、X.509、SSH 等）由 gpg.format 設定變數控制，預設為 OpenPGP。當未指定 -u <key-id> 時，會使用當前使用者的提交者身分來尋找簽署金鑰。設定變數 gpg.program 用於指定自訂的簽署執行檔。

標籤物件（使用 -a、-s 或 -u 建立）稱為「註釋」標籤；它們包含建立日期、標籤製作人姓名與電子郵件、標籤訊息以及可選的密碼學簽章。而「輕量」標籤僅是一個物件的名稱（通常是提交物件）。

註釋標籤適用於發布，而輕量標籤適用於私人或暫時的物件標籤。基於此原因，某些用於命名物件的 git 指令（如 git describe）預設會忽略輕量標籤。

選項

-a
--annotate

建立一個未簽署的註釋標籤物件

-s
--sign

使用預設簽署金鑰建立一個經密碼學簽署的標籤。所使用的簽署後端取決於 gpg.format 設定變數。預設金鑰由後端決定。對於 GPG，它是基於提交者的電子郵件地址，而對於 SSH，它可能是一個特定的金鑰檔案或代理身分。請參閱 git-config[1]。

--no-sign

覆蓋已設定為強制對每個標籤進行簽署的 tag.gpgSign 設定變數。

-u <key-id>
--local-user=<key-id>

使用給定的金鑰建立一個經密碼學簽署的標籤。<key-id> 的格式和所使用的後端取決於 gpg.format 設定變數。請參閱 git-config[1]。

-f
--force

以給定名稱取代現有的標籤（而不是失敗）

-d
--delete

刪除具有給定名稱的現有標籤。

-v
--verify

驗證給定標籤的密碼學簽章。

-n<num>

<num> 指定使用 -l 時要列印註釋中的多少行。隱含 --list。

預設是不列印任何註釋行。如果 -n 未給定數字，則僅列印第一行。如果標籤未註釋，則改為顯示提交訊息。

-l
--list

列出標籤。配合選用的 <pattern>...，例如 git tag --list v-*'，僅列出符合該樣式的標籤。

執行 git tag 而不帶參數也會列出所有標籤。該樣式為 shell 通配符（即使用 fnmatch(3) 比對）。可以給定多個樣式；只要其中任何一個符合，就會顯示該標籤。

如果提供了任何其他類似列表的選項（如 --contains），則會隱含此選項。詳情請參閱各選項的文件。

--sort=<key>

根據給定的鍵進行排序。加上前綴 - 可按值降序排序。您可以多次使用 --sort=<key> 選項，此時最後一個 <key> 將成為主要鍵。也支援 "version:refname" 或 "v:refname"（標籤名稱將被視為版本）。"version:refname" 排序順序也可能受 "versionsort.suffix" 設定變數影響。支援的鍵與 git for-each-ref 中的相同。排序順序預設為 tag.sort 變數配置的值（若存在），否則為字典順序。請參閱 git-config[1]。

--color[=<when>]

尊重 --format 選項中指定的任何顏色。<when> 欄位必須是 always、never 或 auto 之一（如果缺少 <when>，則行為如同給定了 always）。

-i
--ignore-case

排序和篩選標籤時忽略大小寫。

--omit-empty

如果格式展開為空字串，則不在格式化的參照後列印換行符號。

--column[=<options>]
--no-column

以欄位方式顯示標籤列表。請參閱 column.tag 設定變數以了解選項語法。不帶選項的 --column 和 --no-column 分別等同於 always 和 never。

此選項僅適用於列出不含註釋行的標籤時。

--contains [<commit>]

僅列出包含 <commit>（若未指定則為 HEAD）的標籤。隱含 --list。

--no-contains [<commit>]

僅列出不包含 <commit>（若未指定則為 HEAD）的標籤。隱含 --list。

--merged [<commit>]

僅列出可從 <commit>（若未指定則為 HEAD）到達其提交的標籤。

--no-merged [<commit>]

僅列出不可從 <commit>（若未指定則為 HEAD）到達其提交的標籤。

--points-at [<object>]

僅列出 <object>（若未指定則為 HEAD）的標籤。隱含 --list。

-m <msg>
--message=<msg>

使用 <msg>（而不是提示輸入）。如果給定多個 -m 選項，它們的值將會串聯為不同的段落。如果未指定 -a、-s 或 -u <key-id>，則隱含 -a。

-F <file>
--file=<file>

從 <file> 獲取標籤訊息。使用 - 從標準輸入讀取訊息。如果未指定 -a、-s 或 -u <key-id>，則隱含 -a。

--trailer <token>[(=|:)<value>]

指定一個應作為結尾（trailer）套用的 (<token>, <value>) 對。（例如 git tag --trailer "Custom-Key: value" 會將 "Custom-Key" 結尾新增至標籤訊息。）trailer.* 設定變數（git-interpret-trailers[1]）可用於定義是否忽略重複的結尾、每個結尾應出現在結尾列表的何處，以及其他細節。這些結尾可以使用 git tag --list 搭配 --format="%(trailers)" 佔位符進行提取。

-e
--edit

允許進一步編輯透過 -F 檔案取得或透過 -m 命令列取得的訊息。

--cleanup=<mode>

設定如何清理標籤訊息。<mode> 可以是 verbatim、whitespace 和 strip 之一。預設為 strip 模式。verbatim 模式完全不更改訊息，whitespace 僅刪除開頭/結尾的空白行，strip 則同時刪除空白行和註釋。

--create-reflog

為標籤建立 reflog。若要全域啟用標籤的 reflogs，請參閱 git-config[1] 中的 core.logAllRefUpdates。否定形式 --no-create-reflog 僅會覆蓋先前的 --create-reflog，但目前不會否定 core.logAllRefUpdates 的設定。

--format=<format>

一個字串，用於插入所顯示標籤參照及其指向物件的 %(fieldname)。格式與 git-for-each-ref[1] 相同。未指定時，預設為 %(refname:strip=2)。

<tagname>

要建立、刪除或描述的標籤名稱。新標籤名稱必須通過 git-check-ref-format[1] 定義的所有檢查。其中一些檢查可能會限制標籤名稱中允許的字元。

<commit>
<object>

新標籤將參照的物件，通常是提交。預設為 HEAD。

組態設定 (CONFIGURATION)

預設情況下，git tag 在簽署模式（-s）下，會使用您的提交者身分（格式為 您的姓名 <your@email.address>）來尋找金鑰。如果您想使用不同的預設金鑰，可以在儲存庫設定中指定如下：

[user]
    signingKey = <key-id>

簽署後端可以透過 gpg.format 設定變數選擇，預設為 openpgp。請參閱 git-config[1] 以取得其他支援格式的列表。

每個簽署後端所使用程式的路徑，可以使用 gpg.<format>.program 設定變數指定。對於 openpgp 後端，gpg.program 可作為 gpg.openpgp.program 的同義詞。詳細資訊請參閱 git-config[1]。

pager.tag 僅在列出標籤時才生效，即使用或隱含 -l 時。預設是使用分頁器。

更多詳細資訊和其他設定變數，請參閱 git-config[1]。

討論

關於重新打標籤

當您對錯誤的提交打標籤並且想要重新打標籤時，您該怎麼做？

如果您從未推送過任何內容，只需重新打標籤即可。使用 -f 替換舊標籤，這樣就完成了。

但如果您已經推送了內容（或者其他人可以直接讀取您的儲存庫），那麼其他人可能已經看到了舊標籤。在這種情況下，您可以執行以下兩件事之一：

  1. 理性的做法：承認您搞砸了，並使用不同的名稱。其他人已經看到了一個標籤名稱，如果您保留相同的名稱，可能會出現兩個人都有「版本 X」，但實際上卻擁有不同「X」的情況。所以只需稱之為「X.1」並結束它。

  2. 瘋狂的做法：您確實想將新版本也稱為「X」，即使其他人已經看過了舊版本。只需再次使用 git tag -f，就像您還沒發布舊標籤一樣。

然而，Git 不會（也不應該）在使用者不知情的情況下更改標籤。因此，如果有人已經獲取了舊標籤，對您的樹進行 git pull 不應該自動覆蓋他們的舊標籤。

如果有人從您那裡獲取了發布標籤，您不能僅僅透過更新自己的標籤來為他們更改標籤。這是一個重大的安全問題，因為人們必須能夠信任他們的標籤名稱。如果您真的想採取瘋狂的做法，您需要坦白並告訴人們您弄錯了。您可以透過發布一個非常公開的公告來說明：

Ok, I messed up, and I pushed out an earlier version tagged as X. I
then fixed something, and retagged the *fixed* tree as X again.

If you got the wrong tag, and want the new one, please delete
the old one and fetch the new one by doing:

	git tag -d X
	git fetch origin tag X

to get my updated tag.

You can test which tag you have by doing

	git rev-parse X

which should return 0123456789abcdef.. if you have the new version.

Sorry for the inconvenience.

這看起來有點複雜嗎？它應該要這麼複雜。沒有任何方法可以正確地自動「修復」它。人們需要知道他們的標籤可能已被更改。

關於自動跟隨

如果您正在跟隨他人的樹，您很可能正在使用遠端追蹤分支（例如 refs/remotes/origin/master）。您通常希望獲取對端的標籤。

另一方面，如果您進行獲取（fetch）是因為您想要對別人的內容進行一次性合併，您通常不想從那裡獲取標籤。這對於處於頂層（toplevel）的人來說發生得更頻繁，但不限於他們。普通人在互相拉取（pull）時，並不一定想自動從對方那裡獲取私有的錨點標籤。

通常，郵件列表上的「請拉取（please pull）」訊息僅提供兩條資訊：儲存庫 URL 和分支名稱；這旨在方便地貼到 git fetch 命令列的末尾。

Linus, please pull from

	git://git..../proj.git master

to get the following updates...

變為：

$ git pull git://git..../proj.git master

在這種情況下，您不希望自動跟隨對方的標籤。

Git 的一個重要方面是其分散式性質，這在很大程度上意味著系統中沒有固有的「上游」或「下游」。表面上，上述範例可能顯示標籤命名空間是由高層人員所擁有，且標籤僅向下流動，但事實並非如此。它僅顯示使用模式決定了誰對誰的標籤感興趣。

一次性拉取代表著提交歷史現在跨越了兩個群體之間的界線（例如「主要對核心網路部分感興趣的人」），他們可能擁有自己的一套標籤（例如「這是網路組提議供 2.6.21 版本普遍使用的第三個候選發布」），到了另一個群體（例如「整合各個子系統改進的人」）。後者通常對前者內部使用的詳細標籤不感興趣（這就是「內部」的意思）。這就是為什麼在這種情況下最好不要自動跟隨標籤的原因。

很有可能在網路工作者中，他們可能想要交換組內部的標籤，但在該工作流程中，他們很可能透過擁有遠端追蹤分支來追蹤彼此的進度。同樣地，自動跟隨此類標籤的啟發式方法是一件好事。

關於標籤倒填日期

如果您從另一個 VCS 匯入了一些變更，並希望為您的工作的主要發布新增標籤，能夠指定嵌入標籤物件內的日期是很有用的；標籤物件中的此類資料會影響（例如）gitweb 介面中標籤的排序。

要設定未來標籤物件中使用的日期，請設定環境變數 GIT_COMMITTER_DATE（請參閱稍後關於可能值的討論；最常見的形式是「YYYY-MM-DD HH:MM」）。

例如：

$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1

日期格式

GIT_AUTHOR_DATE 和 GIT_COMMITTER_DATE 環境變數支援以下日期格式：

Git 內部格式

格式為 <unix-時間戳記> <時區偏移量>，其中 <unix-時間戳記> 是自 UNIX 紀元以來的秒數。<時區偏移量> 是與 UTC 的正負偏移。例如，CET（比 UTC 快 1 小時）是 +0100。

為了安全起見，建議在 <unix-timestamp> 前面加上 @ (例如 @0 +0000)，這會強制 Git 將其解讀為原始時間戳記。對於小於 100,000,000 的數值（少於 9 位數），這項操作是必須的，以避免與其他日期格式（如 YYYYMMDD）混淆。

RFC 2822

RFC 2822 描述的標準日期格式，例如 Thu, 07 Apr 2005 22:13:13 +0200。

ISO 8601

ISO 8601 標準指定的日期和時間，例如 2005-04-07T22:13:13。解析器也接受以空格替換 T 字元。秒的分數部分將被忽略，例如 2005-04-07T22:13:13.019 將被視為 2005-04-07T22:13:13。

注意
 此外，日期部分接受以下格式：YYYY.MM.DD、MM/DD/YYYY 和 DD.MM.YYYY。

檔案

$GIT_DIR/TAG_EDITMSG

此檔案包含正在進行中的註釋標籤的訊息。如果 git tag 在建立註釋標籤前因錯誤而退出，那麼使用者在編輯器工作階段中提供的標籤訊息將會保留在此檔案中，但可能會被下一次執行 git tag 時覆蓋。

設定

本節中此行以下的內容是從 git-config[1] 文件中選擇性包含的。內容與該處找到的內容相同

tag.forceSignAnnotated

一個布林值，用於指定建立的註釋標籤是否應進行 GPG 簽署。如果在命令列指定了 --annotate，則優先於此選項。

tag.sort

此變數控制 git-tag 顯示標籤時的排序順序。如果未提供 --sort=<value> 選項，將使用此變數的值作為預設值。

tag.gpgSign

一個布林值，用於指定是否應對所有標籤進行 GPG 簽署。在自動化指令碼中執行時使用此選項可能會導致大量標籤被簽署。因此，使用代理來避免多次輸入 GPG 密碼是很方便的。請注意，此選項不會影響由 -u <keyid> 或 --local-user=<keyid> 選項啟用的標籤簽署行為。

注意事項

當合併多個 --contains 和 --no-contains 過濾器時，僅顯示包含至少一個 --contains 提交且不包含任何 --no-contains 提交的參考。

當合併多個 --merged 和 --no-merged 過濾器時，僅顯示可從至少一個 --merged 提交達到且不可從任何 --no-merged 提交達到的參考。

參見

git-check-ref-format[1]. git-config[1].

GIT

git[1] 套件的一部分