簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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>，使得該 blob 可以在 <commit-ish> 中的 <path> 找到，而 <commit-ish> 本身描述了該 blob 在從 HEAD 反向修訂遍歷中出現的第一個提交。

選項

<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 以來指向物件 deadbee…​的第 0 個提交）。

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

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

額外提交的數量是“git log v1.0.4..parent”將顯示的提交數量。雜湊字尾是“-g”+ parent 尖端提交的明確縮寫（它曾是 2414721b194453f058079d897d13c4e377f92dc6）。縮寫的長度隨著倉庫的增長而變化，使用倉庫中物件的近似數量和關於生日悖論的一些數學計算，預設最小長度為 7。“g”字首代表“git”，用於描述軟體的版本，具體取決於管理該軟體的 SCM。這在人們可能使用不同 SCM 的環境中很有用。

對標籤名稱執行 *git describe* 將只顯示標籤名稱

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

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

[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] 套件的一部分

scroll-to-top