簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-sparse-checkout 上次更新於 2.52.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 選項從 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 步驟會將許多跟蹤的檔案（但不包括忽略的檔案）添加回來。除了丟失檔案之外，這種組合的效能和使用者介面也很差。

此外，歷史上，init 在稀疏簽出檔案已存在時不會真正初始化它。這意味著有可能在不記得要將哪些路徑傳遞給後續的 set 或 add 命令的情況下返回到稀疏簽出。但是，--cone 和 --sparse-index 選項不會在 disable 命令之間保留，因此呼叫普通的 init 來輕鬆恢復其效用有所下降。

check-rules

檢查稀疏規則是否匹配一個或多個路徑。

預設情況下，check-rules 從標準輸入讀取路徑列表，並僅輸出與當前稀疏規則匹配的路徑。輸入應每行包含一個路徑，與 git ls-tree --name-only 的輸出匹配，包括以雙引號（"）開頭的路徑名被解釋為 C 風格的引用字串。

當使用 --rules-file <file> 標誌呼叫時，輸入檔案將與 <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 外部的工具寫入檔案，甚至影響 Git 命令，原因可能是特殊情況（例如，在合併/變基時遇到衝突）或因為某些命令不支援完整的稀疏簽出（例如，舊的 recursive 合併後端支援有限）。此命令重新應用現有的稀疏目錄規範，使工作樹與之匹配。

內部機制 — 稀疏簽出

"稀疏簽出" 允許稀疏地填充工作目錄。它使用 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 是索引中的路徑數量。這種擴充套件性很差。

  • 要避免這種擴充套件性問題，必須透過指定前導目錄名或 glob 來限制模式的數量。

  • 在命令列上傳遞 glob 容易出錯，因為使用者可能會忘記引用 glob，導致 shell 將其擴充套件為所有匹配的檔案並將它們單獨傳遞給 sparse-checkout set/add。雖然這對於例如“git grep — *.c”來說也是一個問題，但 grep/log/status 的錯誤會出現在即時輸出中。對於稀疏簽出，錯誤會在執行稀疏簽出命令時被記錄下來，並且可能直到使用者稍後切換分支或執行 rebase 或 merge 時才出現問題，從而在使用者錯誤和他們有機會捕獲/注意到它之間存在延遲。

  • 與上一項相關的是，sparse-checkout 有一個 add 子命令但沒有 remove 子命令。即使添加了 remove 子命令，撤銷意外的未引用 glob 也存在“移除過多”的風險，因為它可能會移除先前由於意外新增而包含的條目。

  • 非錐形模式使用 gitignore 風格的模式來選擇要**包含**的內容（否定模式除外），而 .gitignore 檔案使用 gitignore 風格的模式來選擇要**排除**的內容（否定模式除外）。關於 gitignore 風格模式的文件通常不談論匹配或不匹配，而是談論使用者想要“排除”的內容。這可能會讓使用者在學習如何指定稀疏簽出模式以獲得所需行為時感到困惑。

  • 其他提供某種“特殊路徑模式匹配”的 git 子命令都使用路徑規範，但稀疏簽出的非錐形模式使用 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 補全應該在 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. 遞迴：包含目錄中的所有路徑。

  2. 父級：包含目錄下的直接所有檔案。

由於錐形模式總是包含頂層目錄中的檔案，當執行 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 -- <path> 將確保 <path> 處的子模組存在，而 git submodule deinit [-f] -- <path> 將刪除 <path> 處的子模組檔案（包括任何未跟蹤的檔案、未提交的更改和未推送的歷史）。與稀疏簽出從工作目錄中刪除檔案但仍保留索引中的條目類似，取消初始化的子模組將從工作目錄中刪除，但在索引中仍保留一個條目。

由於子模組可能包含未推送的更改或未跟蹤的檔案，因此刪除它們可能會導致資料丟失。因此，更改稀疏包含/排除規則不會導致已簽出的子模組從工作副本中刪除。換句話說，就像 checkout 不會自動刪除或初始化子模組（即使在切換到刪除或新增子模組的分支之間），使用 sparse-checkout 來減少或擴充套件“有趣”檔案的範圍也不會導致子模組被自動取消初始化或初始化。

此外，上述事實意味著“跟蹤”檔案可能不在工作副本中存在多種原因：來自稀疏簽出的稀疏模式應用，以及子模組初始化狀態。因此，像 git grep 這樣作用於工作副本中跟蹤檔案的命令可能會返回受其中一個或兩個限制結果。

另請參閱

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

GIT

Git[1] 套件的一部分