简体中文 ▾ 主题 ▾ 最新版本 ▾ 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 选项从 stdin 读取。

reapply

将稀疏模式规则重新应用于工作树中的路径。合并或变基之类的命令可以具体化路径以完成其工作（例如，为了向您显示冲突），而其他稀疏检出命令可能无法稀疏化单个文件（例如，因为它具有未暂存的更改或冲突）。在这种情况下，在清理受影响的路径（例如，解决冲突、撤消或提交更改等）之后，稍后运行 git sparse-checkout reapply 可能会更有意义。

reapply 命令还可以使用 --[no-]cone 和 --[no-]sparse-index 标志，其含义与 set 命令中的标志相同，以便更改您正在使用的稀疏模式，而无需重新指定所有稀疏路径。

disable

禁用 core.sparseCheckout 配置设置，并将工作目录恢复为包含所有文件。

init

已弃用的命令，其行为类似于没有指定路径的 set。将来可能会删除。

从历史上看，set 没有处理所有必要的配置设置，这意味着必须同时调用 init 和 set。调用两者意味着 init 步骤首先会删除几乎所有跟踪文件（在锥形模式下，也会删除忽略的文件），然后 set 步骤会将许多跟踪文件（但不包括忽略的文件）添加回来。除了丢失的文件之外，这种组合的性能和 UI 也很差。

此外，从历史上看，如果稀疏检出文件已经存在，init 实际上不会初始化该文件。这意味着可以返回到稀疏检出，而无需记住要传递给后续 set 或 add 命令的路径。但是，--cone 和 --sparse-index 选项不会在 disable 命令中记住，因此调用纯 init 的简易恢复实用程序会降低。

check-rules

检查稀疏规则是否与一个或多个路径匹配。

默认情况下，check-rules 从 stdin 读取路径列表，并仅输出与当前稀疏规则匹配的路径。期望输入由每行一个路径组成，与 git ls-tree --name-only 的输出匹配，包括将以双引号 (") 开头的路径名解释为 C 样式的带引号的字符串。

当使用 --rules-file <file> 标志调用时，输入文件将与 <file> 中找到的稀疏检出规则进行匹配，而不是与当前的稀疏检出规则进行匹配。文件中的规则应该采用与 git sparse-checkout set --stdin 接受的格式相同的格式（特别是，它们必须是换行符分隔的）。

默认情况下，传递给 --rules-file 选项的规则被解释为锥形模式目录。要传递带有 --rules-file 的非锥形模式模式，请将该选项与 --no-cone 选项结合使用。

当使用 -z 标志调用时，在 stdin 上输入的路径以及输出路径的格式都是 \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 合并后端只有有限的支持）。此命令重新应用现有的稀疏目录规范，以使工作目录匹配。

内部机制 — 稀疏检出

"稀疏检出"允许稀疏地填充工作目录。它使用跳过工作树位（参见 git-update-index[1]）来告诉 Git 工作目录中的文件是否值得查看。如果设置了跳过工作树位，并且该文件不存在于工作树中，则其缺失将被忽略。Git 将避免填充这些文件的内容，这使得稀疏检出在处理具有许多文件的存储库时非常有用，但只有少数文件对当前用户很重要。

$GIT_DIR/info/sparse-checkout 文件用于定义跳过工作树引用位图。当 Git 更新工作目录时，它会根据此文件更新索引中的跳过工作树位。与文件中模式匹配的文件将出现在工作目录中，其余文件将不会出现。

内部机制 — 非锥形问题

由 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 子命令都使用路径规范，但稀疏检出的非锥形模式使用 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 将使用更快的基于哈希的算法来计算稀疏检出中的包含。如果它们不匹配，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] 套件的一部分

scroll-to-top