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

名稱

git-sparse-checkout - 將工作樹縮減為已追蹤檔案的子集

概要

git sparse-checkout (init | list | set | add | reapply | disable | check-rules | clean) [<options>]

描述

此指令用於建立稀疏檢出，將工作樹從擁有所有已追蹤檔案的狀態，變更為僅包含這些檔案的子集。它也可以切換目前存在的檔案子集，或者復原並回到工作副本中擁有所有已追蹤檔案的狀態。

檔案子集是透過在錐形模式（預設）下提供目錄清單，或在非錐形模式下提供模式清單來選擇的。

在稀疏檢出中，其他 Git 指令的行為會有些許不同。例如，切換分支不會更新稀疏檢出目錄/模式之外的路徑，且 git commit -a 不會將稀疏檢出目錄/模式之外的路徑記錄為已刪除。

此指令為實驗性質。其行為，以及其他指令在存在稀疏檢出時的行為，未來可能會有所變更。

指令

list

描述稀疏檢出檔案中的目錄或模式。

set

啟用必要的稀疏檢出設定（core.sparseCheckout、core.sparseCheckoutCone 和 index.sparse，如果它們尚未設為所需值），根據 set 子指令後面的參數清單填入稀疏檢出檔案，並更新工作目錄以進行比對。

為了確保調整工作樹內的稀疏檢出設定不會影響其他工作樹中的設定，set 子指令會將您的儲存庫設定升級為使用特定於工作樹的設定（如果尚未啟用）。由 set 子指令參數定義的稀疏性儲存在特定於工作樹的稀疏檢出檔案中。更多詳情請參閱 git-worktree[1] 和 git-config[1] 中的 extensions.worktreeConfig 文件。

當提供 --stdin 選項時，目錄或模式會從標準輸入以換行符分隔的清單讀取，而不是從參數中讀取。

預設情況下，輸入清單被視為目錄清單，與 git ls-tree -d --name-only 的輸出相符。這包括將以雙引號 (") 開頭的路徑名稱解釋為 C 風格的引號字串。請注意，指定目錄下的所有檔案（無論深度）都將包含在稀疏檢出中，以及作為給定目錄或其任何祖先的同級檔案（更多詳情請見下方的「錐形模式集」）。過去這並非預設行為，需要指定 --cone 或啟用 core.sparseCheckoutCone。

當傳入 --no-cone 時，輸入清單被視為模式清單。此模式有許多缺點，包括無法與某些選項（如 --sparse-index）搭配運作。正如下方「非錐形問題」章節所述，我們不建議使用它。

使用 --[no-]sparse-index 選項來使用稀疏索引（預設為不使用）。稀疏索引會縮小索引大小，使其與您的稀疏檢出定義更為貼合。這對於 git status 或 git add 等指令可帶來顯著的效能優勢。此功能目前仍為實驗性質。某些指令在使用稀疏索引時可能會變慢，直到它們與此功能妥善整合為止。

警告： 使用稀疏索引需要以外部工具無法完全理解的方式修改索引。如果您遇到此相容性問題，請執行 git sparse-checkout init --no-sparse-index 來重寫您的索引，使其不再稀疏。舊版 Git 將無法理解稀疏目錄條目索引擴充功能，在停用該功能之前，可能無法與您的儲存庫互動。

add

更新稀疏檢出檔案以包含其他目錄（在錐形模式下）或模式（在非錐形模式下）。預設情況下，這些目錄或模式是從指令列參數讀取的，但也可以使用 --stdin 選項從標準輸入讀取。

reapply

將稀疏模式規則重新應用於工作樹中的路徑。諸如合併或變基之類的指令可能會為了執行工作而實體化路徑（例如，為了向您顯示衝突），且其他稀疏檢出指令可能無法對個別檔案進行稀疏化（例如因為它有未暫存的變更或衝突）。在這種情況下，在清理受影響的路徑（例如解決衝突、復原或提交變更等）之後，執行 git sparse-checkout reapply 是合理的。

reapply 指令也可以接受 --[no-]cone 和 --[no-]sparse-index 旗標，與 set 指令中的旗標含義相同，以便變更您正在使用的稀疏模式，而無需重新指定所有稀疏路徑。

clean

機會性地移除稀疏檢出定義之外的檔案。此指令需要錐形模式才能使用遞迴目錄匹配來確定應移除哪些檔案。如果一個檔案包含在稀疏檢出定義之外的已追蹤目錄中，則該檔案會被納入移除考慮。

某些特殊情況，例如合併衝突或稀疏檢出定義之外的已修改檔案，可能會導致保留原本應被移除的檔案。請解決衝突、暫存修改，並將 git sparse-checkout reapply 與 git sparse-checkout clean 結合使用來處理這些情況。

此指令可用於確保稀疏索引有效運作，儘管它不需要透過 index.sparse=true 設定來啟用稀疏索引功能。

為了防止意外刪除工作樹檔案，clean 子指令在沒有 -f 或 --force 選項的情況下不會刪除任何檔案，除非 clean.requireForce 設定選項被設為 false。

--dry-run 選項將列出將被移除的目錄，而不實際執行刪除。在此模式下執行有助於預測 clean 指令的行為，或確定稀疏目錄中留下了哪些類型的檔案。

--verbose 選項將列出被納入移除考慮目錄中的每一個檔案。此選項有助於確定這些檔案是否真的重要，或解釋為什麼儘管有當前的稀疏檢出，該目錄仍然存在。

disable

停用 core.sparseCheckout 設定，並還原工作目錄以包含所有檔案。

init

已棄用的指令，其行為類似於沒有指定路徑的 set。未來可能會被移除。

在歷史上，set 並未處理所有必要的設定，這意味著必須呼叫 init 和 set。兩者都呼叫意味著 init 步驟會先移除幾乎所有已追蹤的檔案（在錐形模式下，也會移除被忽略的檔案），然後 set 步驟會將許多已追蹤檔案（但不是被忽略的檔案）加回來。除了遺失檔案之外，這種組合的效能和 UI 表現也很差。

此外，在歷史上，如果稀疏檢出檔案已經存在，init 實際上不會初始化它。這意味著有可能在不記住要傳遞給後續 set 或 add 指令的路徑的情況下返回到稀疏檢出。然而，--cone 和 --sparse-index 選項不會在執行 disable 指令後被記住，因此呼叫簡單的 init 來輕鬆還原的效用已降低。

check-rules

檢查稀疏規則是否符合一或多個路徑。

預設情況下，check-rules 會從標準輸入讀取路徑清單，並僅輸出符合當前稀疏規則的路徑。輸入預期為每行一個路徑，與 git ls-tree --name-only 的輸出相符，包括將以雙引號 (") 開頭的路徑名稱解釋為 C 風格的引號字串。

當使用 --rules-file <檔案> 旗標呼叫時，輸入檔案會與 <檔案> 中找到的稀疏檢出規則進行比對，而不是當前的規則。檔案中的規則預期採用 git sparse-checkout set --stdin 可接受的相同形式（特別是，它們必須以換行符分隔）。

預設情況下，傳遞給 --rules-file 選項的規則會被解釋為錐形模式目錄。若要使用 --rules-file 傳遞非錐形模式模式，請將此選項與 --no-cone 選項結合使用。

當使用 -z 旗標呼叫時，標準輸入上輸入的路徑格式以及輸出路徑都將以 \0 終止且不加引號。請注意，這不適用於透過 --rules-file 選項傳遞的規則格式。

範例

git sparse-checkout set MY/DIR1 SUB/DIR2

切換至稀疏檢出，使 MY/DIR1/ 和 SUB/DIR2/ 下的所有檔案（無論深度）都在工作副本中出現（加上 MY/ 和 SUB/ 下方以及頂層目錄中的所有檔案）。如果已經在稀疏檢出中，則將工作副本中出現的檔案變更為此新選集。注意，此指令也會刪除任何不再有已追蹤或未被忽略之未追蹤檔案的目錄中，所有被忽略的檔案。

git sparse-checkout disable

以所有檔案重新填入工作目錄，停用稀疏檢出。

git sparse-checkout add SOME/DIR/ECTORY

將 SOME/DIR/ECTORY/ 下的所有檔案（無論深度）新增至稀疏檢出，以及 SOME/DIR/ 和 SOME/ 下方的所有直接檔案。使用此指令前必須已經在稀疏檢出中。

git sparse-checkout reapply

指令有可能以不符合所選稀疏目錄的方式更新工作樹。這可能源自 Git 外部的工具寫入檔案，甚至因為特殊情況（例如在合併/變基時遇到衝突）或因為某些指令沒有完全支援稀疏檢出（例如舊的 recursive 合併後端僅有有限的支援）而影響 Git 指令。此指令會重新應用現有的稀疏目錄規範，以使工作目錄符合要求。

內部原理 — 稀疏檢出

「稀疏檢出」允許稀疏地填入工作目錄。它使用 skip-worktree 位元（參見 git-update-index[1]）來告知 Git 工作目錄中的檔案是否值得查看。如果設定了 skip-worktree 位元，且檔案不在工作樹中，則會忽略其缺失。Git 將避免填入這些檔案的內容，這使得稀疏檢出在處理擁有許多檔案但只有少數對當前使用者重要的儲存庫時很有幫助。

$GIT_DIR/info/sparse-checkout 檔案用於定義 skip-worktree 參考點陣圖。當 Git 更新工作目錄時，它會根據此檔案更新索引中的 skip-worktree 位元。符合檔案中模式的檔案將出現在工作目錄中，其餘的則不會。

內部原理 — 非錐形問題

由 set 和 add 子指令填入的 $GIT_DIR/info/sparse-checkout 檔案被定義為使用與 .gitignore 檔案相同語法的模式集（每行一個）。在錐形模式下，這些模式僅限於匹配目錄（且使用者僅需提供或查看目錄名稱），而在非錐形模式下，允許任何 gitignore 風格的模式。在非錐形模式下使用完整的 gitignore 風格模式有許多缺點

  • 從根本上來說，它使得各種工作樹更新過程（pull、merge、rebase、switch、reset、checkout 等）需要 O(N*M) 的模式比對，其中 N 是模式數量，M 是索引中的路徑數量。這導致擴展性不佳。

  • 避免擴展性問題必須透過限制模式數量來完成，具體方式是指定前導目錄名稱或萬用字元。

  • 在指令列上傳遞萬用字元容易出錯，因為使用者可能會忘記加引號，導致 shell 將其展開為所有匹配的檔案，並將它們個別傳遞給 sparse-checkout set/add。雖然這在例如「git grep — *.c」中也可能是一個問題，但 grep/log/status 的錯誤會出現在即時輸出中。對於 sparse-checkout，錯誤會在執行 sparse-checkout 指令時被記錄，並且直到使用者稍後切換分支或變基或合併時才會出現問題，從而導致使用者的錯誤與他們有機會發現該錯誤之間存在時間差。

  • 與前一項相關，sparse-checkout 有 add 子指令但沒有 remove 子指令。即使增加了 remove 子指令，復原意外且未加引號的萬用字元也存在「刪除過多」的風險，因為它可能會刪除在意外增加之前就已包含的條目。

  • 非錐形模式使用 gitignore 風格的模式來選擇要 **包含** 的內容（否定模式除外），而 .gitignore 檔案使用 gitignore 風格的模式來選擇要 **排除** 的內容（否定模式除外）。關於 gitignore 風格模式的文檔通常不是從匹配或不匹配的角度討論，而是從使用者想要「排除」什麼的角度討論。這可能會對試圖學習如何指定稀疏檢出模式以獲得其所需行為的使用者造成困惑。

  • 其他每一個想要提供某種「特殊路徑模式匹配」的 git 子指令都使用 pathspec，但稀疏檢出的非錐形模式使用 gitignore 模式，這顯得不一致。

  • 它有一些邊緣情況，「正確」的行為不明確。兩個範例

    首先，兩個使用者在同一個子目錄中，第一個執行

    git sparse-checkout set '/toplevel-dir/*.c'

    而第二個執行

    git sparse-checkout set relative-dir

    那些參數是否應該被轉譯為

    current/subdirectory/toplevel-dir/*.c

    和

    current/subdirectory/relative-dir

    在插入到稀疏檢出檔案之前？輸入第一個指令的使用者可能知道 set/add 的參數在非錐形模式下應該是模式，並且可能對這種轉譯不滿意。然而，許多 gitignore 風格的模式只是路徑，這可能是輸入第二個指令的使用者所想的，如果他們的參數沒有被轉譯，他們會感到不高興。

    其次，對於非錐形使用者，bash-completion 應該在 set/add 指令中補全什麼？如果它建議路徑，是否會加劇上述問題？此外，如果它建議路徑，如果使用者擁有一個以 ! 或 # 開頭，或者名稱中包含 *, \, ?, [ 或 ] 的檔案或目錄怎麼辦？而且如果它建議路徑，它會補全「/pro」為「/proc」（在根檔案系統中）而不是當前目錄中的「/progress.txt」嗎？（注意，使用者很可能希望在非錐形模式下以領先的 / 開頭路徑，原因與 .gitignore 檔案通常包含一個的原因相同。）在所有這些情況下，補全檔案或目錄可能會帶來令人討厭的驚喜。

  • 過度的靈活性使其他擴充功能本質上不切實際。--sparse-index 在非錐形模式下很可能是不可能的；即使以某種方式可行，實作的工作量也大得多，且在實踐中可能太慢。一些為部分複製和稀疏檢出增加耦合的想法，也只有在路徑集更受限制的情況下才切實可行。

基於所有這些原因，非錐形模式已被棄用。請切換至使用錐形模式。

內部原理 — 錐形模式處理

預設的「錐形模式」讓您只能指定要包含的目錄。對於指定的任何目錄，該目錄下的所有路徑都將被包含，且前導目錄（包括頂層目錄）下的任何路徑也將被包含。因此，如果您指定了目錄 Documentation/technical/，則您的稀疏檢出將包含

  • 頂層目錄中的所有檔案

  • Documentation/ 下的所有直接檔案

  • Documentation/technical/ 下任何深度的所有檔案

此外，在錐形模式下，即使沒有指定目錄，頂層目錄中的檔案也會被包含。

當在錐形模式下變更稀疏檢出模式時，Git 將檢查不在稀疏檢出錐形範圍內的每一個已追蹤目錄，以查看其是否包含任何未追蹤檔案。如果所有這些檔案都因為 .gitignore 模式而被忽略，則該目錄將被刪除。如果該目錄內的任何未追蹤檔案未被忽略，則該目錄內不會發生刪除，並會出現警告訊息。如果這些檔案很重要，請重設您的稀疏檢出定義以便將其包含，使用 git add 和 git commit 儲存它們，然後手動移除任何剩餘的檔案，以確保 Git 能發揮最佳效能。

另請參閱「內部原理 — 錐形模式集」章節，以了解目錄在幕後如何轉換為稀疏檢出「完整模式集」的子集。

內部原理 — 完整模式集

完整模式集允許任意模式匹配和複雜的包含/排除規則。在更新索引時，這可能導致 O(N*M) 的模式匹配，其中 N 是模式數量，M 是索引中的路徑數量。為了應對此效能問題，當啟用 core.sparseCheckoutCone 時，允許使用更受限的模式集。

稀疏檢出檔案使用與 .gitignore 檔案相同的語法；詳情請參閱 gitignore[5]。不過，這裡的模式通常用於選擇要包含哪些檔案，而不是要排除哪些檔案。（不過，這可能會讓人感到困惑，因為 gitignore 風格的模式有由以 ! 開頭的模式定義的否定，所以您也可以選擇要「不包含」的檔案。）

例如，要選擇所有內容，然後移除檔案 unwanted（這樣除了名為 unwanted 的檔案外，每個檔案都會出現在您的工作樹中）

git sparse-checkout set --no-cone '/*' '!unwanted'

這些模式會按原樣放入 $GIT_DIR/info/sparse-checkout 中，因此該檔案此時的內容將是

/*
!unwanted

另請參閱 git-read-tree[1] 的「稀疏檢出」章節，以了解更多關於稀疏檢出中使用的 gitignore 風格模式。

內部原理 — 錐形模式集

在錐形模式下，僅接受目錄，但它們會被轉換為完整模式集中使用的相同 gitignore 風格模式。我們將這些模式中使用的特定模式稱為兩種類型之一

  1. 遞迴 (Recursive)： 目錄內的所有路徑都被包含。

  2. 父級 (Parent)： 目錄內的所有直接檔案都被包含。

由於錐形模式總是包含頂層檔案，因此在執行沒有指定目錄的 git sparse-checkout set 時，頂層目錄會作為父級模式被新增。此時，稀疏檢出檔案包含以下模式

/*
!/*/

這表示「包含頂層目錄下的所有內容，但該層級下方的任何層級都不包含」。

當在錐形模式下時，git sparse-checkout set 子指令接受目錄清單。指令 git sparse-checkout set A/B/C 將目錄 A/B/C 設定為遞迴模式，目錄 A 和 A/B 被新增為父級模式。產生的稀疏檢出檔案現在是

/*
!/*/
/A/
!/A/*/
/A/B/
!/A/B/*/
/A/B/C/

這裡，順序很重要，因此否定模式會被檔案中較後出現的肯定模式所覆蓋。

除非 core.sparseCheckoutCone 被顯式設為 false，否則 Git 將解析稀疏檢出檔案並預期這些類型的模式。如果模式不符，Git 將會發出警告。如果模式符合預期格式，則 Git 將使用更快的雜湊演算法來計算稀疏檢出中的包含情況。如果不符，git 的行為將如同 core.sparseCheckoutCone 為 false 一樣，無論其設定為何。

在錐形模式下，儘管完整的模式被寫入 $GIT_DIR/info/sparse-checkout 檔案，git sparse-checkout list 子指令仍會列出定義遞迴模式的目錄。對於上述範例稀疏檢出檔案，輸出如下

$ git sparse-checkout list
A/B/C

如果 core.ignoreCase=true，則模式匹配演算法將使用不區分大小寫的檢查。這修正了 git sparse-checkout set 指令中大小寫不匹配的檔案名稱，以反映工作目錄中預期的錐形。

內部原理 — 子模組

如果您的儲存庫包含一或多個子模組，則子模組會根據與 git submodule 指令的互動來進行填入。具體來說，git submodule init -- <路徑> 將確保位於 <路徑> 的子模組存在，而 git submodule deinit [-f] -- <路徑> 將移除位於 <路徑> 的子模組檔案（包括任何未追蹤檔案、未提交的變更和未推送的歷史紀錄）。類似於稀疏檢出從工作樹中移除檔案但仍在索引中留下條目，已取消初始化的子模組會從工作目錄中移除，但在索引中仍有條目。

由於子模組可能具有未推送的變更或未追蹤的檔案，移除它們可能會導致資料遺失。因此，變更稀疏包含/排除規則不會導致已檢出的子模組從工作副本中移除。換句話說，正如 checkout 不會導致子模組自動被移除或初始化，即使在移除或新增子模組的分支之間切換時也是如此，使用 sparse-checkout 來縮減或擴大「感興趣」檔案的範圍也不會導致子模組自動取消初始化或初始化。

此外，上述事實意味著「已追蹤」檔案可能不在工作副本中有以下多種原因：來自稀疏檢出的稀疏模式應用，以及子模組初始化狀態。因此，諸如 git grep 等處理工作副本中已追蹤檔案的指令，其返回的結果可能會受到這些限制中的一個或兩者的限制。

參見

git-read-tree[1] gitignore[5]

GIT

git[1] 套件的一部分