Git
英文 ▾ 主題 ▾ 最新版本 ▾ 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>

描述

此命令會尋找從某個 commit 可以到達的最近標籤。如果標籤指向該 commit，則僅顯示該標籤。否則，它會將標籤名稱加上標記物件之上的其他 commit 數量，以及最近 commit 的縮寫物件名稱作為後綴。結果會是一個「人類可讀」的物件名稱，也可以用來向其他 git 命令識別該 commit。

預設情況下（沒有 --all 或 --tags），git describe 僅顯示附註標籤。關於建立附註標籤的詳細資訊，請參閱 git-tag[1] 的 -a 和 -s 選項。

如果給定的物件指的是一個 blob，則會將其描述為 <commit-ish>:<path>，以便可以在 <commit-ish> 的 <path> 中找到該 blob，而 <commit-ish> 本身則描述了在從 HEAD 反向修訂過程中，此 blob 出現的第一個 commit。

選項

<commit-ish>…​

要描述的 Commit-ish 物件名稱。如果省略，則預設為 HEAD。

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

描述工作目錄的狀態。當工作目錄與 HEAD 相符時，輸出結果與 "git describe HEAD" 相同。如果工作目錄有本地修改，則會在後面附加 "-dirty"。如果儲存庫已損壞，且 Git 無法判斷是否有本地修改，則 Git 將會報錯，除非給定 '--broken'，否則會在後面附加 "-broken" 作為後綴。

--all

不只使用附註標籤，而是使用在 refs/ 命名空間中找到的任何參考。此選項啟用比對任何已知的分支、遠端追蹤分支或輕量型標籤。

--tags

不只使用附註標籤，而是使用在 refs/tags 命名空間中找到的任何標籤。此選項啟用比對輕量型（非附註）標籤。

--contains

不要尋找早於該 commit 的標籤，而是尋找該 commit 之後的標籤，因此其中包含該 commit。自動隱含 --tags。

--abbrev=<n>

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

--candidates=<n>

不要只考慮最近的 10 個標籤作為描述輸入 commit-ish 的候選項，而是考慮最多 <n> 個候選項。將 <n> 增加到 10 以上會花費稍微長一點的時間，但可能會產生更準確的結果。<n> 為 0 將會導致僅輸出完全符合的項目。

--exact-match

僅輸出完全符合的項目（標籤直接參考提供的 commit）。這是 --candidates=0 的同義詞。

--debug

詳細顯示關於用於標準錯誤的搜尋策略的資訊。標籤名稱仍然會列印到標準輸出。

--long

即使符合標籤，也一律輸出長格式（標籤、commit 數量和縮寫 commit 名稱）。當您想要在 "describe" 輸出中看到 commit 物件名稱的部分時，即使相關的 commit 碰巧是已標記的版本，這也很有用。它不會僅發出標籤名稱，而是會將此類 commit 描述為 v1.2-0-gdeadbee（自指向物件 deadbee…​ 的標籤 v1.2 以來的第 0 個 commit）。

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

顯示唯一縮寫的 commit 物件作為備用。

--first-parent

看到合併 commit 時，僅追蹤第一個父 commit。當您不想比對目標 commit 歷史記錄中合併的分支上的標籤時，這很有用。

範例

使用類似 git.git 當前樹狀結構的東西，我得到

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

也就是說，我的「父」分支的當前 HEAD 是基於 v1.0.4，但由於它在之上有一些 commit，因此 describe 在最後新增了額外的 commit 數量（「14」）和該 commit 本身的縮寫物件名稱（「2414721」）。

額外的 commit 數量是 "git log v1.0.4..parent" 將會顯示的 commit 數量。雜湊後綴為 "-g" + 父分支頂端 commit 的明確縮寫（它是 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 開頭的新 commit，這些 commit 在當時並不存在，並且單獨的 "-g975b" 後綴可能不足以消除這些 commit 的歧義。

搜尋策略

對於每個提供的 commit-ish，git describe 會先尋找完全標記該 commit 的標籤。帶註解的標籤將永遠優先於輕量級標籤，而日期較新的標籤將永遠優先於日期較舊的標籤。如果找到完全匹配的標籤，則會輸出其名稱並停止搜尋。

如果找不到完全匹配的標籤，git describe 將會回溯 commit 歷史，以找到一個已標記的祖先 commit。該祖先的標籤將會輸出，並附帶輸入的 commit-ish 的 SHA-1 的縮寫。如果指定了 --first-parent，則回溯只會考慮每個 commit 的第一個父 commit。

如果在回溯過程中找到多個標籤，則會選擇與輸入的 commit-ish 差異 commit 數最少的標籤並輸出。這裡的「差異 commit 數最少」定義為 git log tag..input 所顯示的 commit 數量盡可能最少。

錯誤

無法描述樹狀物件以及未指向 commit 的標籤物件。在描述 blob 時，指向 blob 的輕量級標籤會被忽略，但儘管輕量級標籤較為有利，blob 仍然會被描述為 <commit-ish>:<path>。

GIT

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

scroll-to-top