簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-sparse-checkout 最後更新於 2.42.0

名稱

git-sparse-checkout - 將你的工作樹縮減為跟蹤檔案的一個子集

概要

git sparse-checkout (init | list | set | add | reapply | disable | check-rules) [<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 PATTERN SET）。過去，這並不是預設設定，需要指定 --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 命令的標誌相同，以便更改你正在使用的稀疏模式，而無需重新指定所有稀疏路徑。

disable（停用）

停用 core.sparseCheckout 配置設定，並將工作目錄恢復為包含所有檔案。

init（初始化）

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

從歷史上看，set 命令並未處理所有必要的配置設定，這意味著必須同時呼叫 init 和 set。同時呼叫兩者意味著 init 步驟會首先刪除幾乎所有跟蹤檔案（在錐形模式下，也包括忽略的檔案），然後 set 步驟會添加回許多跟蹤檔案（但不包括忽略的檔案）。除了丟失的檔案，這種組合的效能和使用者介面也很差。

此外，從歷史上看，如果稀疏檢出檔案已經存在，init 命令實際上不會初始化它。這意味著可以在不記住要傳遞給後續 set 或 add 命令的路徑的情況下返回到稀疏檢出。然而，--cone 和 --sparse-index 選項在停用命令後不會被記住，因此呼叫簡單的 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 的錯誤會立即出現在輸出中。對於 sparse-checkout，錯誤在 sparse-checkout 命令執行時被記錄，並且可能直到使用者稍後切換分支、變基或合併時才出現問題，從而在使用者錯誤和他們有機會發現/注意到錯誤之間造成延遲。

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

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

  • 所有其他想要提供某種“特殊路徑模式匹配”的 git 子命令都使用 pathspecs，但 sparse-checkout 的非錐形模式使用 gitignore 模式，這感覺不一致。

  • 它存在“正確”行為不明確的邊緣情況。兩個示例：

    First, two users are in a subdirectory, and the first runs
   git sparse-checkout set '/toplevel-dir/*.c'
while the second runs
   git sparse-checkout set relative-dir
Should those arguments be transliterated into
   current/subdirectory/toplevel-dir/*.c
and
   current/subdirectory/relative-dir
before inserting into the sparse-checkout file?  The user who typed
the first command is probably aware that arguments to set/add are
supposed to be patterns in non-cone mode, and probably would not be
happy with such a transliteration.  However, many gitignore-style
patterns are just paths, which might be what the user who typed the
second command was thinking, and they'd be upset if their argument
wasn't transliterated.
    Second, what should bash-completion complete on for set/add commands
for non-cone users?  If it suggests paths, is it exacerbating the
problem above?  Also, if it suggests paths, what if the user has a
file or directory that begins with either a '!' or '#' or has a '*',
'\', '?', '[', or ']' in its name?  And if it suggests paths, will
it complete "/pro" to "/proc" (in the root filesystem) rather than to
"/progress.txt" in the current directory?  (Note that users are
likely to want to start paths with a leading '/' in non-cone mode,
for the same reason that .gitignore files often have one.)
Completing on files or directories might give nasty surprises in
all these cases.

  • 過度的靈活性使得其他擴充套件基本上不切實際。--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 將使用更快的基於雜湊的演算法來計算稀疏檢出中的包含。如果它們不匹配，無論 core.sparseCheckoutCone 的設定如何，Git 的行為都將如同它被設定為 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] 套件的一部分

scroll-to-top