簡體中文 ▾ 主題 ▾ 最新版本 ▾ gitrevisions 最後更新於 2.42.0

名稱

gitrevisions - 為 Git 指定修訂版本和範圍

概要

gitrevisions

描述

許多 Git 命令都接受修訂版本引數作為引數。根據命令的不同，它們可以表示特定的提交，或者對於遍歷修訂圖的命令（例如 git-log[1]），它們表示從該提交可到達的所有提交。對於遍歷修訂圖的命令，也可以顯式指定一個修訂版本範圍。

此外，一些 Git 命令（例如 git-show[1] 和 git-push[1]）也可以接受表示除提交以外的其他物件的修訂版本引數，例如 blob（“檔案”）或 tree（“檔案目錄”）。

指定修訂版本

修訂版本引數 <rev> 通常（但不總是）命名一個提交物件。它使用所謂的“擴充套件 SHA-1”語法。以下是表示物件名稱的各種方式。列表中靠近末尾的那些方式命名了提交中包含的 tree 和 blob。

注意
 本文件展示了 Git 所見的“原始”語法。shell 和其他 UI 可能需要額外的引用來保護特殊字元並避免單詞拆分。
<sha1>，例如 dae86e1950b1277e545cee180551750029cfe735、dae86e

完整的 SHA-1 物件名稱（40位元組十六進位制字串），或在倉庫中唯一的前導子字串。例如，如果倉庫中沒有其他物件名稱以 `dae86e` 開頭，那麼 `dae86e1950b1277e545cee180551750029cfe735` 和 `dae86e` 都指向相同的提交物件。

<describeOutput>，例如 v1.7.4.2-679-g3bee7fb

git describe 的輸出；即最近的標籤，後面可選地跟一個短劃線和提交數量，再跟一個短劃線、一個 g 和一個縮寫物件名稱。

<refname>，例如 master、heads/master、refs/heads/master

一個符號引用名稱。例如，master 通常指 refs/heads/master 所引用的提交物件。如果你碰巧同時有 heads/master 和 tags/master，你可以明確地寫 heads/master 來告訴 Git 你指的是哪一個。當存在歧義時，<refname> 會透過以下規則中的第一個匹配項進行消除歧義：

  1. 如果 $GIT_DIR/<refname> 存在，這就是你所指的（這通常只對 HEAD、FETCH_HEAD、ORIG_HEAD、MERGE_HEAD、REBASE_HEAD、REVERT_HEAD、CHERRY_PICK_HEAD、BISECT_HEAD 和 AUTO_MERGE 有用）；

  2. 否則，如果 refs/<refname> 存在；

  3. 否則，如果 refs/tags/<refname> 存在；

  4. 否則，如果 refs/heads/<refname> 存在；

  5. 否則，如果 refs/remotes/<refname> 存在；

  6. 否則，如果 refs/remotes/<refname>/HEAD 存在。

    HEAD

    命名了你在工作樹中基於其進行更改的提交。

    FETCH_HEAD

    記錄了你上次呼叫 git fetch 從遠端倉庫拉取的（fetched）分支。

    ORIG_HEAD

    由大幅度移動 `HEAD` 的命令（git am、git merge、git rebase、git reset）建立，用於記錄操作前 HEAD 的位置，以便你可以輕鬆地將分支的尖端（tip）恢復到執行這些命令之前的狀態。

    MERGE_HEAD

    當你執行 git merge 時，記錄了你正在合併到你的分支中的提交。

    REBASE_HEAD

    在 rebase 過程中，記錄了當前操作停止時的提交，原因可能是衝突或互動式 rebase 中的 edit 命令。

    REVERT_HEAD

    當你執行 git revert 時，記錄了你正在還原的提交。

    CHERRY_PICK_HEAD

    當你執行 git cherry-pick 時，記錄了你正在 cherry-pick 的提交。

    BISECT_HEAD

    當你執行 git bisect --no-checkout 時，記錄了當前要測試的提交。

    AUTO_MERGE

    記錄了一個 tree 物件，該物件對應於當合並操作導致衝突時，ort 合併策略寫入工作樹的狀態。

請注意，上述任何 refs/* 情況都可以來自 $GIT_DIR/refs 目錄或 $GIT_DIR/packed-refs 檔案。雖然引用名稱編碼未指定，但首選 UTF-8，因為一些輸出處理可能會假定引用名稱為 UTF-8。

@

@ 僅是 HEAD 的快捷方式。

[<refname>]@{<date>}，例如 master@{yesterday}、HEAD@{5 minutes ago}

引用後跟帶有日期規範（例如 {yesterday}、{1 month 2 weeks 3 days 1 hour 1 second ago} 或 {1979-02-26 18:30:00}）的花括號字尾 @，指定了引用在過去某個時間點的值。此後綴只能緊跟在引用名稱之後使用，並且該引用必須具有現有的日誌（$GIT_DIR/logs/<ref>）。請注意，這會查詢你的本地引用在給定時間的狀態；例如，你本地 master 分支上週有什麼。如果你想檢視在特定時間段內進行的提交，請參閱 --since 和 --until。

<refname>@{<n>}，例如 master@{1}

引用後跟帶有序數規範（例如 {1}、{15}）的花括號字尾 @，指定了該引用的第 n 個先前值。例如，master@{1} 是 master 的緊鄰先前值，而 master@{5} 是 master 的第 5 個先前值。此後綴只能緊跟在引用名稱之後使用，並且該引用必須具有現有的日誌（$GIT_DIR/logs/<refname>）。

@{<n>}，例如 @{1}

你可以使用帶有空引用部分的 @ 結構來獲取當前分支的 reflog 條目。例如，如果你在分支 blabla 上，那麼 @{1} 與 blabla@{1} 含義相同。

@{-<n>}，例如 @{-1}

構造 @{-<n>} 表示當前分支/提交之前檢出的第 <n> 個分支/提交。

[<branchname>]@{upstream}，例如 master@{upstream}、@{u}

分支 B 可以設定為基於遠端 R（透過 branch.<name>.remote 配置）上的分支 X（透過 branch.<name>.merge 配置）進行構建。B@{u} 指的是從遠端 R 獲取的分支 X 的遠端跟蹤分支，通常位於 refs/remotes/R/X。

[<branchname>]@{push}，例如 master@{push}、@{push}

字尾 @{push} 報告瞭如果 git push 被執行而 branchname 被檢出時（如果未指定分支名稱則為當前的 HEAD），“我們將推送到的”分支。與 @{upstream} 類似，我們報告了遠端上與該分支對應的遠端跟蹤分支。

以下是一個更清晰的例子：

$ git config push.default current
$ git config remote.pushdefault myfork
$ git switch -c mybranch origin/master

$ git rev-parse --symbolic-full-name @{upstream}
refs/remotes/origin/master

$ git rev-parse --symbolic-full-name @{push}
refs/remotes/myfork/mybranch

請注意，在示例中我們設定了一個三角形工作流，即從一個位置拉取（pull）並推送到另一個位置。在非三角形工作流中，@{push} 與 @{upstream} 相同，因此沒有必要使用它。

該字尾在大小寫方面均可接受，並且無論大小寫如何，含義都相同。

<rev>^[<n>]，例如 HEAD^、v1.5.1^0

修訂版本引數後的字尾 ^ 表示該提交物件的第一個父級。^<n> 表示第 <n> 個父級（即 <rev>^ 等同於 <rev>^1）。作為一條特殊規則，<rev>^0 表示提交本身，並且當 <rev> 是引用提交物件的標籤物件的名稱時使用。

<rev>~[<n>]，例如 HEAD~、master~3

修訂版本引數後的字尾 ~ 表示該提交物件的第一個父級。修訂版本引數後的字尾 ~<n> 表示指定提交物件的第 <n> 代祖先提交物件，只跟隨第一個父級。即 <rev>~3 等同於 <rev>^^^，後者又等同於 <rev>^1^1^1。有關此形式用法的說明，請參見下文。

<rev>^{<type>}，例如 v0.99.8^{commit}

字尾 ^ 後跟一對花括號中包含的物件型別名稱，表示遞迴地解引用 <rev> 處的物件，直到找到型別為 <type> 的物件，或者該物件無法再被解引用為止（在這種情況下，將報錯）。例如，如果 <rev> 是一個 commit-ish，<rev>^{commit} 描述了相應的提交物件。類似地，如果 <rev> 是一個 tree-ish，<rev>^{tree} 描述了相應的 tree 物件。<rev>^0 是 <rev>^{commit} 的簡寫。

<rev>^{object} 可用於確保 <rev> 命名了一個存在的物件，而無需 <rev> 是一個標籤，也無需解引用 <rev>；因為標籤本身就是一個物件，它甚至無需解引用就能得到一個物件。

<rev>^{tag} 可用於確保 <rev> 識別一個現有的標籤物件。

<rev>^{}，例如 v0.99.8^{}

字尾 ^ 後跟一對空花括號，表示該物件可能是一個標籤，並遞迴解引用該標籤，直到找到一個非標籤物件。

<rev>^{/<text>}，例如 HEAD^{/fix nasty bug}

修訂版本引數後的字尾 ^，後跟一對包含以斜槓開頭的文字的花括號，其含義與下面 :/fix nasty bug 語法相同，不同之處在於它返回的是在 ^ 之前從 <rev> 可達到的最新匹配提交。

:/<text>，例如 :/fix nasty bug

冒號後跟斜槓，再後跟文字，命名一個提交，其提交訊息與指定的正則表示式匹配。此名稱返回從任何引用（包括 HEAD）可到達的最新匹配提交。正則表示式可以匹配提交訊息的任何部分。要匹配以某個字串開頭的訊息，可以使用例如 :/^foo。特殊序列 :/! 保留用於匹配內容的修飾符。:/!-foo 執行否定匹配，而 :/!!foo 匹配字面字元 !，後跟 foo。任何其他以 :/! 開頭的序列目前都保留。根據給定的文字，shell 的單詞拆分規則可能需要額外的引用。

<rev>:<path>，例如 HEAD:README、master:./README

字尾 : 後跟路徑，命名了冒號前部分所命名的 tree-ish 物件中給定路徑處的 blob 或 tree。以 ./ 或 ../ 開頭的路徑是相對於當前工作目錄的。給定的路徑將被轉換為相對於工作樹的根目錄。這在從具有與工作樹相同樹結構的提交或樹中引用 blob 或 tree 時最有用。

:[<n>:]<path>，例如 :0:README、:README

冒號，可選地後跟一個階段編號（0到3）和一個冒號，再後跟路徑，命名了索引中給定路徑處的 blob 物件。缺失階段編號（及其後的冒號）表示階段 0 條目。在合併期間，階段 1 是共同祖先，階段 2 是目標分支的版本（通常是當前分支），階段 3 是正在合併的分支的版本。

以下是 Jon Loeliger 的一個圖示。提交節點 B 和 C 都是提交節點 A 的父級。父級提交按從左到右的順序排列。

G   H   I   J
 \ /     \ /
  D   E   F
   \  |  / \
    \ | /   |
     \|/    |
      B     C
       \   /
        \ /
         A
A =      = A^0
B = A^   = A^1     = A~1
C =      = A^2
D = A^^  = A^1^1   = A~2
E = B^2  = A^^2
F = B^3  = A^^3
G = A^^^ = A^1^1^1 = A~3
H = D^2  = B^^2    = A^^^2  = A~2^2
I = F^   = B^3^    = A^^3^
J = F^2  = B^3^2   = A^^3^2

指定範圍

歷史遍歷命令（例如 git log）對一組提交進行操作，而不僅僅是單個提交。

對於這些命令，使用前一節中描述的符號指定單個修訂版本，意味著從給定提交可到達的提交集合。

指定多個修訂版本意味著從任何給定提交可到達的提交集合。

提交的可達集合是提交本身及其祖先鏈中的提交。

有幾種表示一組相互關聯的提交（稱為“修訂版本範圍”）的符號，如下所示。

提交排除

^<rev>（插入符號）表示法

要排除從某個提交可到達的提交，使用字首 ^ 表示法。例如，^r1 r2 表示從 r2 可到達但排除從 r1 可到達的提交（即 r1 及其祖先）。

點式範圍表示法

..（兩點）範圍表示法

^r1 r2 集合操作出現得非常頻繁，因此有其簡寫形式。當你擁有兩個提交 r1 和 r2（根據上面“指定修訂版本”中解釋的語法命名）時，你可以透過 ^r1 r2 要求從 r2 可達但排除從 r1 可達的提交，這也可以寫成 r1..r2。

...（三點）對稱差表示法

類似的符號 r1...r2 稱為 r1 和 r2 的對稱差，定義為 r1 r2 --not $(git merge-base --all r1 r2)。它是從 r1（左側）或 r2（右側）兩者之一可到達但不能同時從兩者可到達的提交集合。

在這兩種簡寫表示法中，你可以省略一端，使其預設為 HEAD。例如，origin.. 是 origin..HEAD 的簡寫，它表示“自從我從 origin 分支分叉以來我做了什麼？”。類似地，..origin 是 HEAD..origin 的簡寫，它表示“自從我從他們那裡分叉以來 origin 做了什麼？”。請注意，.. 將表示 HEAD..HEAD，這是一個既可從 HEAD 到達又不可從 HEAD 到達的空範圍。

專門設計用於接受兩個不同範圍的命令（例如“`git range-diff R1 R2`”用於比較兩個範圍）確實存在，但它們是例外。除非另有說明，所有對一組提交進行操作的“git”命令都在單個修訂版本範圍內工作。換句話說，將兩個“兩點範圍表示法”並排書寫，例如

$ git log A..B C..D

對於大多數命令，**不會**指定兩個修訂版本範圍。相反，它會命名一個單一的連線提交集合，即那些可以從 B 或 D 到達但不能同時從 A 或 C 到達的提交。在像這樣的線性歷史中

---A---B---o---o---C---D

因為 A 和 B 可以從 C 到達，所以這兩個點式範圍指定的修訂版本範圍是單個提交 D。

其他 <rev>^ 父級簡寫表示法

存在另外三種簡寫形式，特別適用於合併提交，用於命名由一個提交及其父級提交組成的集合。

r1^@ 表示法意味著 r1 的所有父級。

r1^! 表示法包括提交 r1 但排除其所有父級。就其本身而言，此表示法表示單個提交 r1。

<rev>^-[<n>] 表示法包括 <rev> 但排除第 <n> 個父級（即 <rev>^<n>..<rev> 的簡寫），如果未給出 <n>，則 <n> = 1。這通常對於合併提交很有用，你可以只傳遞 <commit>^- 來獲取在合併提交 <commit> 中合併的所有分支提交（包括 <commit> 本身）。

儘管 <rev>^<n> 是關於指定單個提交父級，但這三種表示法也考慮其父級。例如，你可以說 HEAD^2^@，但你不能說 HEAD^@^2。

修訂版本範圍總結

<rev>

包括從 <rev> 可到達的提交（即 <rev> 及其祖先）。

^<rev>

排除從 <rev> 可到達的提交（即 <rev> 及其祖先）。

<rev1>..<rev2>

包括從 <rev2> 可到達但排除從 <rev1> 可到達的提交。當 <rev1> 或 <rev2> 被省略時，它預設為 HEAD。

<rev1>...<rev2>

包括從 <rev1> 或 <rev2> 之一可到達但排除從兩者都可到達的提交。當 <rev1> 或 <rev2> 被省略時，它預設為 HEAD。

<rev>^@，例如 HEAD^@

字尾 ^ 後跟一個“@”符號，與列出 <rev> 的所有父級相同（意思是，包括從其父級可到達的所有內容，但不包括提交本身）。

<rev>^!，例如 HEAD^!

字尾 ^ 後跟一個感嘆號，與給出提交 <rev> 及其所有父級（以 ^ 為字首以排除它們及其祖先）相同。

<rev>^-<n>，例如 HEAD^-、HEAD^-2

等同於 <rev>^<n>..<rev>，如果未給出 <n>，則 <n> = 1。

以下是一些使用上面 Loeliger 圖示的例子，其中表示法的每個展開和選擇步驟都詳細闡述：

   Args   Expanded arguments    Selected commits
   D                            G H D
   D F                          G H I J D F
   ^G D                         H D
   ^D B                         E I J F B
   ^D B C                       E I J F B C
   C                            I J F C
   B..C   = ^B C                C
   B...C  = B ^F C              G H D E B C
   B^-    = B^..B
	  = ^B^1 B              E I J F B
   C^@    = C^1
	  = F                   I J F
   B^@    = B^1 B^2 B^3
	  = D E F               D G H E F I J
   C^!    = C ^C^@
	  = C ^C^1
	  = C ^F                C
   B^!    = B ^B^@
	  = B ^B^1 ^B^2 ^B^3
	  = B ^D ^E ^F          B
   F^! D  = F ^I ^J D           G H D F

另請參閱

git-rev-parse[1]

GIT

Git[1] 套件的一部分

scroll-to-top