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

名稱

git-tag - 建立、列出、刪除或驗證以 GPG 簽署的標籤物件

概要

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> 其中之一，則命令會建立標籤物件，並需要標籤訊息。除非指定 -m <msg> 或 -F <file>，否則會啟動編輯器以供使用者輸入標籤訊息。

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

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

當使用 -s 或 -u <key-id> 時，會建立 GnuPG 簽署的標籤物件。當未使用 -u <key-id> 時，會使用目前使用者的提交者身分來尋找簽署用的 GnuPG 金鑰。組態變數 gpg.program 用於指定自訂 GnuPG 二進位檔。

標籤物件（使用 -a、-s 或 -u 建立）稱為「已註解」標籤；它們包含建立日期、標籤者姓名和電子郵件、標籤訊息，以及可選的 GnuPG 簽名。而「輕量」標籤只是物件（通常是提交物件）的名稱。

已註解標籤用於發布，而輕量標籤用於私人或暫時的物件標籤。因此，一些用於命名物件的 git 命令（例如 git describe）預設會忽略輕量標籤。

選項

-a
--annotate

建立未簽署的已註解標籤物件

-s
--sign

使用預設電子郵件地址的金鑰建立 GPG 簽署的標籤。標籤 GPG 簽署的預設行為由 tag.gpgSign 組態變數控制（如果存在），否則會停用。請參閱 git-config[1]。

--no-sign

覆寫 tag.gpgSign 組態變數，該變數設定為強制簽署每個標籤。

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

使用給定的金鑰建立 GPG 簽署的標籤。

-f
--force

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

-d
--delete

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

-v
--verify

驗證指定標籤名稱的 GPG 簽名。

-n<num>

<num> 指定在使用 -l 時要列印的註解行數（如果有的話）。隱含 --list。

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

-l
--list

列出標籤。使用可選的 <pattern>...，例如 git tag --list 'v-*'，只列出符合模式的標籤。

不帶引數執行「git tag」也會列出所有標籤。模式是 shell 通配符（即，使用 fnmatch(3) 進行匹配）。可以提供多個模式；如果任何一個模式匹配，則會顯示標籤。

如果提供任何其他類似清單的選項（例如 --contains），則會隱含提供此選項。有關詳細資訊，請參閱每個選項的文件。

--sort=<key>

根據給定的鍵排序。在值前面加上 - 可依遞減順序排序。您可以多次使用 --sort=<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>]

僅列出包含指定提交的標籤（如果未指定，則為 HEAD）。隱含 --list。

--no-contains [<commit>]

僅列出不包含指定提交的標籤（如果未指定，則為 HEAD）。隱含 --list。

--merged [<commit>]

僅列出其提交可從指定提交存取的標籤（如果未指定，則為 HEAD）。

--no-merged [<commit>]

僅列出其提交無法從指定提交存取的標籤（如果未指定，則為 HEAD）。

--points-at <object>

僅列出給定物件的標籤（如果未指定，則為 HEAD）。隱含 --list。

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

使用指定的標籤訊息（而不是提示）。如果提供多個 -m 選項，它們的值將會被串接成不同的段落。如果沒有提供 -a、-s 或 -u <key-id>，則會隱含 -a。

-F <檔案>
--file=<檔案>

從指定的檔案取得標籤訊息。使用 - 從標準輸入讀取訊息。如果沒有提供 -a、-s 或 -u <key-id>，則會隱含 -a。

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

指定一個 (<token>, <value>) 配對，該配對應作為 trailer 應用。（例如，git tag --trailer "Custom-Key: value" 將會新增一個 "Custom-Key" trailer 到標籤訊息。）trailer.* 設定變數 (git-interpret-trailers[1]) 可用於定義是否省略重複的 trailer、每個 trailer 會出現在 trailer 順序中的哪個位置，以及其他詳細資訊。可以使用 --format="%(trailers)" 佔位符在 git tag --list 中提取 trailer。

-e
--edit

從檔案使用 -F 和從命令列使用 -m 取得的訊息通常會以未修改的方式用作標籤訊息。此選項可讓您進一步編輯從這些來源取得的訊息。

--cleanup=<模式>

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

--create-reflog

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

--format=<格式>

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

<標籤名稱>

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

<提交>
<物件>

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

組態

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

[user]
    signingKey = <gpg-key-id>

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）。您通常希望從另一端取得標籤。

另一方面，如果您進行提取是因為您想要從其他人那裡進行一次性合併，您通常不希望從那裡取得標籤。這種情況對於接近頂層的人來說更常發生，但不限於他們。當普通人在彼此之間進行提取時，不一定希望自動取得對方的私人錨點標籤。

通常，郵件列表上的「請提取」訊息僅提供兩條資訊：一個儲存庫 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-timestamp> <time-zone-offset>，其中 <unix-timestamp> 是自 UNIX 紀元以來的秒數。<time-zone-offset> 是與 UTC 的正或負偏移量。例如，CET（比 UTC 早 1 小時）是 +0100。

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 覆寫。

注意事項

當組合多個 --contains 和 --no-contains 篩選器時，只會顯示包含至少一個 --contains 提交且不包含任何 --no-contains 提交的參照。

當組合多個 --merged 和 --no-merged 篩選器時，只會顯示可從至少一個 --merged 提交且從任何 --no-merged 提交都無法存取的參照。

另請參閱

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

GIT

屬於 git[1] 套件的一部分

scroll-to-top