簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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> 之一，則此命令會建立一個 tag 物件，並要求提供標籤訊息。除非提供了 -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>
--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。

配置

預設情況下，處於預設簽名模式 (-s) 的 git tag 將使用您的提交者身份（形式為 Your Name <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 版本普遍使用而提議的第三個候選釋出版本”）。後者通常對前一個組內部使用的詳細標籤不感興趣（這就是“內部”的含義）。這就是為什麼在這種情況下不自動跟蹤標籤是可取的。

很可能在網路領域的人員之間，他們可能希望交換其組內部的標籤，但在該工作流程中，他們很可能透過遠端跟蹤分支來跟蹤彼此的進展。同樣，自動跟蹤此類標籤的啟發式方法是一件好事。

關於回溯標籤日期

如果您從其他版本控制系統匯入了一些更改，並希望為您的工作主要版本新增標籤，那麼能夠指定要嵌入標籤物件中的日期會很有用；標籤物件中的此類資料會影響（例如）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