簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-tag 最後更新於 2.52.0

名稱

git-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>]

指定一個（<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。要全域性啟用標籤的 reflog，請參閱 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。

配置

預設情況下，git tag 在簽名預設模式（-s）下會使用您的提交者身份（形式為 Your Name <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）。您通常需要來自對方的標籤。

另一方面，如果您正在獲取，因為您想要一個一次性的合併，您通常不希望從中獲取標籤。這種情況更多發生在接近頂層的人身上，但不僅限於他們。普通人在互相拉取時，不一定希望自動獲取對方的私有錨點標籤。

通常，郵件列表上的“請拉取”訊息只提供兩個資訊：一個儲存庫 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 的一個重要方面是其分散式特性，這意味著系統中不存在固有的“上游”或“下游”。表面上看，上面的例子可能表明標籤名稱空間由高層人士擁有，並且標籤只向下流動，但事實並非如此。它只表明使用模式決定了誰對誰的標籤感興趣。

一次性拉取是提交歷史現在正在跨越一個圈子的人（例如，“主要對核心網路部分感興趣的人”）到另一個圈子的人（例如，“整合各種子系統改進的人”）的邊界的標誌。後者通常對前者組內部使用的詳細標籤不感興趣（這就是“內部”的含義）。這就是為什麼在這種情況下不希望自動跟隨標籤。

也許網路領域的人員希望交換他們內部的標籤，但在那種工作流程中，他們很可能透過遠端跟蹤分支來跟蹤彼此的進度。再次，自動跟隨此類標籤的啟發式方法是件好事。

關於回溯標籤

如果您從其他 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 覆蓋。

配置

本節中以下所有內容均從 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] 套件的一部分