Git

gitrevisions 最後更新於 2.42.0

名稱

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

概要

gitrevisions

說明

許多 Git 命令會將修訂版本參數作為引數。根據命令的不同，它們表示特定的提交，或者對於走訪修訂圖的命令 (例如 git-log[1])，表示從該提交可到達的所有提交。對於走訪修訂圖的命令，也可以明確指定修訂版本的範圍。

此外，某些 Git 命令 (例如 git-show[1] 和 git-push[1]) 也可以採用表示提交以外的其他物件的修訂版本參數，例如 blobs ("檔案") 或 trees ("檔案目錄")。

指定修訂版本

修訂版本參數 <rev> 通常 (但不一定) 指定一個提交物件。它使用所謂的擴展 SHA-1 語法。以下是拼寫物件名稱的各種方式。此列表末尾列出的名稱指定提交中包含的樹狀結構和 blob。

注意	此文件顯示 git 所看到的 "原始" 語法。 shell 和其他 UI 可能需要額外的引號來保護特殊字元並避免單字分割。

<sha1>，例如 dae86e1950b1277e545cee180551750029cfe735、dae86e

完整的 SHA-1 物件名稱 (40 位元組的十六進位字串)，或在存放庫中唯一的領先子字串。例如，dae86e1950b1277e545cee180551750029cfe735 和 dae86e 都指定相同的提交物件，如果你的存放庫中沒有其他物件的物件名稱以 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> 會按照以下規則找到第一個匹配的項目：

如果 $GIT_DIR/<refname> 存在，那就是你所指的 (這通常僅對 HEAD、FETCH_HEAD、ORIG_HEAD、MERGE_HEAD、REBASE_HEAD、REVERT_HEAD、CHERRY_PICK_HEAD、BISECT_HEAD 和 AUTO_MERGE 有用)；
否則，如果 refs/<refname> 存在，則使用該項；
否則，如果 refs/tags/<refname> 存在，則使用該項；
否則，如果 refs/heads/<refname> 存在，則使用該項；
否則，如果 refs/remotes/<refname> 存在，則使用該項；
否則，如果 refs/remotes/<refname>/HEAD 存在，則使用該項。

HEAD

指定你變更工作樹時所依據的提交。

FETCH_HEAD

記錄你上次使用 git fetch 呼叫從遠端存放庫提取的分支。

ORIG_HEAD

由以激烈的方式移動 HEAD 的命令 (git am、git merge、git rebase、git reset) 所建立，用於記錄其操作之前的 HEAD 位置，以便你可以輕鬆將分支的尖端變更回執行它們之前的狀態。

MERGE_HEAD

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

REBASE_HEAD

在變基期間，記錄目前操作停止的提交，可能是因為衝突，也可能是因為互動式變基中的 edit 命令。

REVERT_HEAD

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

CHERRY_PICK_HEAD

記錄當你執行 git cherry-pick 時，你要挑選的提交。

BISECT_HEAD

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

AUTO_MERGE

記錄對應於當合併操作導致衝突時，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}

你可以使用 @ 結構搭配空的參考部分來取得目前分支的參考記錄項目。例如，如果你在 blabla 分支上，則 @{1} 的意思與 blabla@{1} 相同。

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

結構 @{-<n>} 表示在目前分支/提交之前檢查出的第 <n> 個分支/提交。

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

分支 B 可能設定為建構於遠端 R 的分支 X 之上（透過 branch.<name>.merge 設定）。B@{u} 指的是遠端 R 上分支 X 的遠端追蹤分支，通常位於 refs/remotes/R/X。

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

後綴詞 @{push} 會回報當 branchname 被檢出時（或如果沒有指定 branchname 則為目前的 HEAD），執行 git push 會「推送到哪裡」的分支。如同 @{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

請注意，在範例中，我們設定了一個三角工作流程，從一個位置拉取，並推送到另一個位置。在非三角工作流程中，@{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} 描述對應的樹狀物件。<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 或樹狀結構。以 ./ 或 ../ 開頭的路徑是相對於目前工作目錄。給定的路徑將會轉換為相對於工作樹根目錄的路徑。這對於從與工作樹具有相同樹狀結構的提交或樹狀結構中尋址 blob 或樹狀結構最有用。

:[<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 之類的歷程記錄瀏覽命令，作用於一組提交，而不僅僅是單一提交。

對於這些命令，使用上一節中描述的表示法，指定單一修訂，表示可從給定提交 reachable 的提交集。

指定多個修訂表示可從任何給定提交 reachable 的提交集。

提交的 reachable 集是提交本身及其祖先鏈中的提交。

有幾種表示法可以指定一組已連線的提交（稱為「修訂範圍」），如下所示。

提交排除

^<rev>（插入符號）表示法: 若要排除可從提交 reachable 的提交，則使用前綴 ^ 表示法。例如，^r1 r2 表示可從 r2 reachable 的提交，但排除可從 r1 reachable 的提交（即 r1 及其祖先）。

點狀範圍表示法

..（雙點）範圍表示法: ^r1 r2 的集合運算非常頻繁，因此有一個簡寫。當您有兩個提交 r1 和 r2（根據上面「指定修訂」中說明語法命名）時，您可以使用 ^r1 r2 要求從 r2 reachable 的提交，但不包括可從 r1 reachable 的提交，並且可以將其寫為 r1..r2。
...（三點）對稱差異表示法: 類似的表示法 r1...r2 稱為 r1 和 r2 的對稱差異，並定義為 r1 r2 --not $(git merge-base --all r1 r2)。它是可從 r1（左側）或 r2（右側）其中一個 reachable，但不能從兩者 reachable 的提交集。

在這兩個簡寫表示法中，您可以省略其中一端，讓它預設為 HEAD。例如，origin.. 是 origin..HEAD 的簡寫，並詢問「自我從 origin 分支分叉以來我做了什麼？」。同樣地，..origin 是 HEAD..origin 的簡寫，並詢問「自我從他們分叉以來，origin 做了什麼？」。請注意，.. 表示 HEAD..HEAD，這是一個從 HEAD 既可到達又不可到達的空範圍。

專門設計用於採用兩個不同範圍的命令（例如，「git range-diff R1 R2」以比較兩個範圍）確實存在，但它們是例外。除非另有說明，所有作用於一組提交的「git」命令都作用於單一修訂範圍。換句話說，將兩個「雙點範圍表示法」並排寫在一起，例如

$ git log A..B C..D

對於大多數命令，不會指定兩個修訂範圍。相反地，它將命名單一連線的提交集，也就是可從 B 或 D reachable，但不可從 A 或 C reachable 的提交。在如下的線性歷程記錄中

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

由於 A 和 B 可從 C reachable，因此這兩個點狀範圍指定的修訂範圍是單一提交 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> reachable 的提交（即 <rev> 及其祖先）。
^<rev>: 排除可從 <rev> reachable 的提交（即 <rev> 及其祖先）。
<rev1>..<rev2>: 包括可從 <rev2> reachable 的提交，但排除可從 <rev1> reachable 的提交。當 <rev1> 或 <rev2> 其中一者省略時，預設為 HEAD。
<rev1>...<rev2>: 包括可從 <rev1> 或 <rev2> 其中一者 reachable 的提交，但排除可從兩者 reachable 的提交。當 <rev1> 或 <rev2> 其中一者省略時，預設為 HEAD。
<rev>^@，例如：HEAD^@: 後綴詞 ^ 後面接著 @ 符號，與列出 <rev> 的所有父系相同（表示，包括從其父系 reachable 的所有內容，但不包括提交本身）。
<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[1] 套件的一部分

設定與配置

取得與建立專案

基本快照

分支與合併

分享與更新專案

檢查與比較

修補

除錯

電子郵件

外部系統

伺服器管理

指南

管理

底層命令

名稱

概要

說明