簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-describe 上次更新於 2.42.0

名稱

git-describe - 根據可用的引用為物件命名，生成可讀性強的名稱

概要

git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>…​]
git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
git describe <blob>

描述

該命令會查詢從某個提交可達的最近的標籤。如果標籤指向該提交，則只顯示標籤。否則，它會在標籤名後附加標籤物件上的額外提交數量和最近提交的縮寫物件名稱。結果是一個“人類可讀”的物件名稱，也可用於標識其他 git 命令的提交。

預設情況下 (不帶 --all 或 --tags)，git describe 只顯示帶註釋的標籤。有關建立帶註釋標籤的更多資訊，請參閱 git-tag[1] 的 -a 和 -s 選項。

如果指定的物件指向一個 blob，它將被描述為 <commit-ish>:<path>，以便在 <commit-ish> 的 <path> 處找到該 blob，其中 <commit-ish> 本身描述了從 HEAD 反向遍歷提交歷史時，該 blob 首次出現的提交。

選項

<commit-ish>…​

要描述的提交-引用物件名稱。如果省略，則預設為 HEAD。

--dirty[=<mark>]
--broken[=<mark>]

描述工作樹的狀態。當工作樹與 HEAD 匹配時，輸出與“git describe HEAD”相同。如果工作樹有本地修改，則在其後附加“-dirty”。如果儲存庫損壞且 Git 無法確定是否存在本地修改，Git 將報錯，除非給定了‘--broken’，它將附加“-broken”字尾。

--all

不只使用帶註釋的標籤，而是使用 refs/ 名稱空間中找到的任何引用。此選項啟用匹配任何已知分支、遠端跟蹤分支或輕量級標籤。

--tags

不只使用帶註釋的標籤，而是使用 refs/tags 名稱空間中找到的任何標籤。此選項啟用匹配輕量級（非帶註釋）標籤。

--contains

不查詢在提交之前存在的標籤，而是查詢在提交之後存在幷包含該提交的標籤。自動隱含 --tags。

--abbrev=<n>

不使用十六進位制數字的預設數量（這將根據儲存庫中的物件數量變化，預設為 7）來表示縮寫的物件名稱，而是使用 <n> 位數字，或者直到形成唯一物件名稱所需的最少位數。<n> 為 0 將抑制長格式，只顯示最近的標籤。

--candidates=<n>

不只考慮最近的 10 個標籤作為描述輸入提交-引用的候選，而是考慮最多 <n> 個候選。增加 <n> (大於 10) 會稍微花費更多時間，但可能會產生更準確的結果。<n> 為 0 時，將只輸出精確匹配。

--exact-match

只輸出精確匹配（一個標籤直接引用了提供的提交）。這是 --candidates=0 的同義詞。

--debug

冗餘地顯示正在使用的搜尋策略的資訊到標準錯誤。標籤名仍會列印到標準輸出。

--long

始終輸出長格式（標籤、提交數和縮寫提交名），即使它匹配一個標籤。當您想在“describe”輸出中看到提交物件名稱的某些部分，即使該提交恰好是已標記版本時，此選項很有用。它不會只輸出標籤名，而是將這樣的提交描述為 v1.2-0-gdeadbee（自標籤 v1.2 以來的第 0 個提交，指向物件 deadbee...）。

--match <pattern>

只考慮匹配給定 glob(7) 模式的標籤，排除“refs/tags/”字首。如果與 --all 一起使用，它還會考慮匹配模式的本地分支和遠端跟蹤引用，分別排除“refs/heads/”和“refs/remotes/”字首；其他型別的引用永遠不會被考慮。如果多次使用，將累積模式列表，並考慮匹配任何模式的標籤。使用 --no-match 來清除和重置模式列表。

--exclude <pattern>

不考慮匹配給定 glob(7) 模式的標籤，排除“refs/tags/”字首。如果與 --all 一起使用，它也不會考慮匹配模式的本地分支和遠端跟蹤引用，分別排除“refs/heads/”和“refs/remotes/”字首；其他型別的引用永遠不會被考慮。如果多次使用，將累積模式列表，並將排除匹配任何模式的標籤。當與 --match 結合使用時，一個標籤將在其至少匹配一個 --match 模式並且不匹配任何 --exclude 模式時被考慮。使用 --no-exclude 來清除和重置模式列表。

--always

顯示唯一縮寫的提交物件作為後備。

--first-parent

在遇到合併提交時，只跟蹤第一個父提交。當你希望不匹配目標提交歷史中合併的分支上的標籤時，這個選項很有用。

示例

在類似 git.git 當前樹的情況下，我得到

[torvalds@g5 git]$ git describe parent
v1.0.4-14-g2414721

即我的“父”分支的當前 HEAD 基於 v1.0.4，但由於它在該版本之上還有一些提交，describe 添加了額外提交的數量（“14”）和提交本身的縮寫物件名稱（“2414721”）在末尾。

額外提交的數量是“git log v1.0.4..parent”將顯示的提交數量。雜湊字尾是“-g”加上 parent 的 tip 提交（它是 2414721b194453f058079d897d13c4e377f92dc6）的不明確縮寫。縮寫的長度隨著儲存庫的增長而變化，使用儲存庫中的物件數量和一些關於生日悖論的數學計算，預設為最少 7 位。 “g”字首代表“git”，用於允許描述依賴於軟體所管理 SCM 的軟體版本。這在人們可能使用不同 SCM 的環境中很有用。

對標籤名進行git describe 操作將只顯示標籤名

[torvalds@g5 git]$ git describe v1.0.4
v1.0.4

使用 --all 時，該命令可以使用分支頭作為引用，因此輸出也會顯示引用路徑

[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
tags/v1.0.0-21-g975b
[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
heads/lt/describe-7-g975b

將 --abbrev 設定為 0 時，該命令可用於查詢不帶任何字尾的最接近的標籤名

[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
tags/v1.0.0

請注意，今天輸入這些命令時你得到的字尾可能比 Linus 在他執行這些命令時看到的要長，因為你的 Git 儲存庫可能有新的提交，其物件名稱以 975b 開頭，而這些提交在他那時並不存在，因此僅“-g975b”字尾可能不足以區分這些提交。

搜尋策略

對於提供的每個提交-引用，git describe 將首先查詢一個精確標記該提交的標籤。帶註釋的標籤總是優先於輕量級標籤，並且日期較新的標籤總是優先於日期較舊的標籤。如果找到精確匹配，將輸出其名稱並停止搜尋。

如果未找到精確匹配，git describe 將透過提交歷史向後遍歷以定位一個已標記的祖先提交。將輸出祖先的標籤以及輸入提交-引用的 SHA-1 的縮寫。如果指定了 --first-parent，則遍歷將只考慮每個提交的第一個父提交。

如果在遍歷過程中找到多個標籤，將選擇並輸出與輸入提交-引用相差提交數最少的標籤。這裡的相差提交數最少定義為 git log tag..input 將顯示的提交數量是可能的最小數量。

BUG

樹物件以及指向非提交物件的標籤無法被描述。在描述 blob 時，指向 blob 的輕量級標籤將被忽略，但 blob 仍將被描述為 <commit-ish>:<path>，即使輕量級標籤更受青睞。

GIT

Git[1] 套件的一部分