English ▾ 主題 ▾ 最新版本 ▾ git-apply 最後更新於 2.55.0

名稱

git-apply - 將補丁(patch)應用於檔案及/或索引(index)

概要

git apply [--stat] [--numstat] [--summary] [--check]
	  [--index | --intent-to-add] [--3way] [--ours | --theirs | --union]
	  [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
	  [--allow-binary-replacement | --binary] [--reject] [-z]
	  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
	  [--ignore-space-change | --ignore-whitespace]
	  [--whitespace=(nowarn|warn|fix|error|error-all)]
	  [--exclude=<path>] [--include=<path>] [--directory=<root>]
	  [--verbose | --quiet] [--unsafe-paths] [--allow-empty] [<patch>…​]

描述

讀取提供的 diff 輸出(即「補丁」)並將其應用於檔案。當在儲存庫的子目錄中執行時,該目錄以外的補丁路徑會被忽略。使用 --index 選項時,補丁也會應用於索引;使用 --cached 選項時,補丁僅應用於索引。若無這些選項,該指令僅將補丁應用於檔案,且不需要這些檔案位於 Git 儲存庫中。

此指令會應用補丁但不會建立提交(commit)。若要從 git-format-patch[1] 產生的補丁建立提交,或從電子郵件接收補丁並建立提交,請使用 git-am[1]

選項

<patch>...

讀取補丁的來源檔案。可以使用 - 從標準輸入讀取。

--stat

不應用補丁,而是輸出輸入內容的 diffstat。會關閉「應用(apply)」功能。

--numstat

--stat 類似,但以十進位標記顯示新增與刪除的行數,並顯示未縮寫的路徑名稱,以便於機器處理。對於二進位檔案,會輸出兩個 - 而非顯示 0 0。會關閉「應用(apply)」功能。

--summary

不應用補丁,而是從 git diff 擴充標頭中取得資訊並輸出摘要,例如建立檔案、重新命名及模式變更。會關閉「應用(apply)」功能。

--check

不應用補丁,而是檢查該補丁是否能應用於目前的工作樹及/或索引檔案,並檢測錯誤。會關閉「應用(apply)」功能。

--index

將補丁同時應用於索引和工作樹(若啟用 --check,則僅檢查是否能乾淨地應用於兩者)。請注意,--index 要求相關路徑的索引項目與工作樹複本必須完全一致(其內容與檔案模式等詮釋資料必須相符),如果兩者不一致,即使補丁能分別乾淨地應用於索引和工作樹,也會引發錯誤。

--cached

僅將補丁應用於索引,不更動工作樹。若啟用 --check,則僅檢查該補丁是否能乾淨地應用於索引項目。

-N
--intent-to-add

僅將補丁應用於工作樹時,將新檔案標記為稍後加入索引(參見 git-add[1] 中的 --intent-to-add 選項)。如果使用了 --index--cached,此選項會被忽略,且在 Git 儲存庫外無效。請注意,--index 可能會被其他選項(如 --3way)隱含啟用。

-3
--3way

如果補丁記錄了其應應用的 blob 識別資訊,且我們在本地擁有這些 blob,則嘗試進行三方合併(3-way merge),這可能會將衝突標記留在工作樹的檔案中供使用者解決。此選項隱含了 --index 選項(除非使用了 --cached 選項),且與 --reject 選項不相容。與 --cached 選項搭配使用時,任何衝突都會保留在快取的較高階段(higher stages)。

--ours
--theirs
--union

不將衝突留在檔案中,而是以偏好我們一方(或對方、或兩者)的方式解決衝突。需要搭配 --3way

--build-fake-ancestor=<file>

較新的 git diff 輸出會為每個 blob 嵌入索引資訊,以協助識別補丁所應用的原始版本。當給定此旗標,且原始版本的 blob 可在本地取得時,會建立一個包含這些 blob 的臨時索引。

當遇到純模式變更(沒有索引資訊)時,該資訊會從目前的索引讀取。

-R
--reverse

反向應用補丁。

--reject

為了原子性,git apply 預設在部分片段(hunk)無法應用時,會使整個補丁失效且不更動工作樹。此選項使其能應用可用的補丁部分,並將遭拒絕的片段留在對應的 *.rej 檔案中。

-z

當給定 --numstat 時,不處理路徑名稱,而是使用以 NUL 字元結尾的機器可讀格式。

若不使用此選項,具有「不尋常」字元的路徑名稱將按照配置變數 core.quotePath 的說明進行引用(參見 git-config[1])。

-p<n>

從傳統的 diff 路徑中移除<n>個開頭的路徑組件(以斜線分隔)。例如,使用 -p2 時,針對 a/dir/file 的補丁會直接應用於 file。預設值為 1。

-C<n>

確保每次變更前後至少有<n>行周圍上下文(context)相符。當存在的周圍上下文少於<n>行時,必須全部相符。預設情況下,不會忽略任何上下文。

--unidiff-zero

預設情況下,git apply 預期套用的補丁是包含至少一行上下文的統一 diff (unified diff)。這提供了良好的安全措施,但在應用使用 --unified=0 產生的 diff 時會失效。若要略過這些檢查,請使用 --unidiff-zero

注意,基於上述原因,不建議使用無上下文的補丁。

--apply

如果您使用了上述標記為「會關閉應用(apply)」的選項,git apply 會讀取並輸出請求的資訊,而不會實際應用補丁。在這些旗標之後加上此旗標,即可同時應用補丁。

--no-add

應用補丁時,忽略補丁中的新增內容。這可用於提取兩個檔案之間的共通部分,方法是先對它們執行 diff,然後使用此選項應用結果,這會套用刪除部分但不套用新增部分。

--allow-binary-replacement
--binary

歷史上,未經使用者明確許可,我們不允許應用二進位補丁,而此旗標是當時達成此目的的方式。目前我們總是允許應用二進位補丁,因此此選項已無實際作用(no-op)。

--exclude=<path-pattern>

不將變更應用於符合<path-pattern>的檔案。在匯入補丁集時,若您想排除特定檔案或目錄,這會很有用。

--include=<path-pattern>

將變更應用於符合<path-pattern>的檔案。在匯入補丁集時,若您只想包含特定檔案或目錄,這會很有用。

當同時使用 --exclude--include 模式時,它們會按照在指令列中出現的順序進行檢查,第一次匹配的結果決定了該路徑的補丁是否被使用。如果指令列中沒有 include 模式,預設會使用不符合任何 include/exclude 模式的路徑的補丁;如果存在任何 include 模式,則這類路徑會被忽略。

--ignore-space-change
--ignore-whitespace

應用補丁時,必要時忽略上下文行中的空白字元變更。上下文行會保留其空白字元,且不會受到 --whitespace 選項值的影響進行空白修正。不過,新行仍會被修正。

--whitespace=<action>

應用補丁時,偵測是否有空白字元錯誤的新行或已修改行。何謂空白字元錯誤由 core.whitespace 設定控制。預設情況下,行尾空白(包含僅由空白字元組成的行)以及行首縮排中緊接在定位字元(tab)後的空白字元被視為空白字元錯誤。

預設情況下,該指令會輸出警告訊息,但仍會應用補丁。當 git-apply 用於統計而非應用補丁時,預設值為 nowarn

您可以使用不同的<action>值來控制此行為:

  • nowarn 關閉行尾空白警告。

  • warn 對少數此類錯誤輸出警告,但按原樣應用補丁(預設值)。

  • fix 對少數此類錯誤輸出警告,並在修正錯誤後應用補丁(strip 是其同義詞——舊工具僅將行尾空白字元視為錯誤,並透過「去除(stripping)」它們來修正,但現代 Git 做得更多)。

  • error 對少數此類錯誤輸出警告,並拒絕應用補丁。

  • error-allerror 類似,但會顯示所有錯誤。

--inaccurate-eof

在某些情況下,某些版本的 diff 無法正確偵測檔案結尾缺少換行符的情況。結果導致由此類 diff 程式建立的補丁無法正確記錄不完整的行。此選項透過繞過此錯誤來增加對應用此類補丁的支援。

-v
--verbose

向 stderr 報告進度。預設僅會列印有關目前套用補丁的訊息。此選項會導致報告額外的資訊。

-q
--quiet

抑制 stderr 輸出。有關補丁狀態和進度的訊息將不會列印。

--recount

不信任片段標頭中的行數統計,而是透過檢查補丁來推斷(例如在編輯補丁而未適當調整片段標頭後)。

--directory=<root>

<root>附加至所有檔案名稱開頭。如果同時傳遞了 -p 引數,它會在附加新根目錄前先套用。

例如,一個關於將 a/git-gui.sh 更新為 b/git-gui.sh 的補丁,可以透過執行 git apply --directory=modules/git-gui 應用於工作樹中的 modules/git-gui/git-gui.sh

--unsafe-paths

預設情況下,影響工作區域之外(無論是 Git 控制的工作樹,還是將 git apply 作為 GNU patch 的替代品使用時的目前工作目錄)的補丁會被視為錯誤(或惡意行為)而被拒絕。

git apply 被用作「更好的 GNU patch」時,使用者可以傳遞 --unsafe-paths 選項來覆寫此安全檢查。當使用 --index--cached 時,此選項無效。

--allow-empty

對於不包含 diff 的補丁不回傳錯誤。這包括空補丁以及僅包含提交說明文字的補丁。

組態設定 (CONFIGURATION)

本節中此行以下的內容是從 git-config[1] 文件中選擇性包含的。內容與該處找到的內容相同

apply.ignoreWhitespace

當設定為 change 時,指示 git apply 忽略空白字元變更,方式與 --ignore-space-change 選項相同。當設定為 nononeneverfalse 之一時,指示 git apply 尊重所有空白字元差異。

apply.whitespace

指示 git apply 如何處理空白字元,方式與 --whitespace 選項相同。

子模組

如果補丁包含對子模組的任何變更,git apply 將按以下方式處理這些變更:

如果指定了 --index(無論是顯式還是隱式),則子模組提交必須與索引完全相符,補丁才能套用。如果已簽出(check-out)任何子模組,則這些簽出內容將被完全忽略,即它們不需要保持最新或乾淨,且不會被更新。

如果未指定 --index,則補丁中的子模組提交將被忽略,僅檢查相應子目錄是否存在,並(如果可能)進行更新。

參見

GIT

git[1] 套件的一部分