git-update-index - 将工作树中的文件内容注册到索引

修改索引。每个提到的文件都将更新到索引中，任何未合并或需要更新状态都将被清除。

有关在索引上执行一些最常见操作的更友好的方法，请参阅 git-add[1]。

git update-index 处理其被告知的文件的方式可以使用各种选项进行修改

--refresh 不会计算新的 sha1 文件，也不会针对模式/内容更改更新索引。但它 **确实** 做的是将文件的 stat 信息与索引“重新匹配”，以便您可以刷新索引以查看未更改但 stat 条目过时的文件。

例如，您想要在执行 git read-tree 后执行此操作，以将 stat 索引详细信息与正确的文件关联起来。

--cacheinfo 用于注册当前工作目录中不存在的文件。这对最小检出合并很有用。

要假装您在指定路径上有一个具有指定模式和 sha1 的文件，请执行以下操作

--info-only 用于注册文件而不将其放入对象数据库中。这对只读状态的存储库很有用。

--cacheinfo 和 --info-only 的行为相似：索引会更新，但对象数据库不会更新。--cacheinfo 在对象位于数据库中但文件在本地不可用时很有用。--info-only 在文件可用但您不想更新对象数据库时很有用。

--index-info 是一种更强大的机制，它允许您从标准输入中输入多个条目定义，并专门为脚本设计。它可以接受三种格式的输入

要将更高阶的阶段条目放入索引中，应首先通过为该路径提供一个 mode=0 的条目来删除该路径，然后以第三种格式提供必要的输入行。

例如，从以下索引开始

您可以将以下输入提供给 --index-info

输入的第一行提供了 0 作为模式来删除该路径；SHA-1 不重要，只要它格式正确即可。然后，第二行和第三行提供了该路径的阶段 1 和阶段 2 条目。在执行上述操作之后，我们将得到以下结果

Git 中的许多操作都依赖于您的文件系统拥有高效的 lstat(2) 实现，以便可以廉价地检查工作树文件的 st_mtime 信息，以查看文件内容是否已从索引文件中记录的版本发生更改。不幸的是，有些文件系统拥有低效的 lstat(2)。如果您的文件系统是其中之一，您可以将“假设未更改”位设置为您未更改的路径，以使 Git 不执行此检查。请注意，在路径上设置此位并不意味着 Git 会检查文件内容以查看它是否已更改——它使 Git 省略任何检查并假设它 **未** 更改。当您更改工作树文件时，您必须通过删除“假设未更改”位来显式地告诉 Git，无论是在修改之前还是之后。

为了设置“假设未更改”位，请使用 --assume-unchanged 选项。要取消设置，请使用 --no-assume-unchanged。要查看哪些文件设置了“假设未更改”位，请使用 git ls-files -v（请参阅 git-ls-files[1]）。

该命令会查看 core.ignorestat 配置变量。当此变量为 true 时，使用 git update-index paths... 更新的路径以及使用其他更新索引和工作树的 Git 命令（例如 git apply --index、git checkout-index -u 和 git read-tree -u）更新的路径将自动标记为“假设未更改”。请注意，如果 git update-index --refresh 发现工作树文件与索引匹配，则 **不会** 设置“假设未更改”位（如果您想将它们标记为“假设未更改”，请使用 git update-index --really-refresh）。

有时用户会将假设未更改位与跳过工作树位混淆。请参阅下面“跳过工作树位”部分的最后一段，了解这两个位之间的区别。

要仅更新和刷新已检出的文件

跳过工作树位可以用一句话（很长）来定义：告诉 git 在合理的情况下避免将文件写入工作目录，并在文件不存在于工作目录中时将其视为未更改。

请注意，并非所有 git 命令都会关注此位，并且有些命令只部分支持它。

与跳过工作树位相关的 update-index 标志和 read-tree 功能早于 git-sparse-checkout[1] 命令的引入，该命令提供了一种更简单的方法来配置和处理跳过工作树位。如果您想将您的工作树缩减为只处理存储库中的部分路径，我们强烈建议您使用 git-sparse-checkout[1] 而不是低级 update-index 和 read-tree 原语。

跳过工作树位的首要目的是启用稀疏检出，即让工作目录只包含部分路径。当设置了跳过工作树位时，Git 命令（例如 switch、pull、merge）将避免写入这些文件。但是，这些命令有时会在重要情况下（例如合并或变基期间的冲突）写入这些文件。Git 命令还会避免将这些文件的缺失视为故意删除；例如 git add -u 不会为这些文件暂存删除操作，git commit -a 也不会提交删除这些文件的操作。

虽然此位看起来与假设未更改位类似，但它的目标不同。假设未更改位用于将文件保留在工作树中，但让 Git 省略对其更改的检查并假设文件未更改（尽管如果它可以在不使用 stat 的情况下确定它已更改，它可以自由记录这些更改）。跳过工作树告诉 Git 忽略文件缺失，在可能的情况下避免使用通常更新大部分工作目录的命令（例如 checkout、switch、pull 等）来更新它，并且不将它的缺失记录到提交中。请注意，在稀疏检出（通过 git sparse-checkout 设置或通过将 core.sparseCheckout 配置为 true 设置）中，如果索引中将文件标记为跳过工作树，但它在工作树中被发现，Git 将清除该文件的跳过工作树位。

此模式专为索引非常大的存储库而设计，旨在减少重复写入这些索引所需的时间。

在此模式下，索引被拆分为两个文件：$GIT_DIR/index 和 $GIT_DIR/sharedindex.<SHA-1>。更改累积在 $GIT_DIR/index（拆分索引）中，而共享索引文件包含所有索引条目并保持不变。

当拆分索引中的条目数量达到 splitIndex.maxPercentChange 配置变量（请参阅 git-config[1]）指定的级别时，拆分索引中的所有更改都会被推回共享索引文件中。

每次创建新的共享索引文件时，如果旧的共享索引文件的修改时间早于 splitIndex.sharedIndexExpire 配置变量（请参阅 git-config[1]）指定的修改时间，则会将其删除。

为了避免删除仍在使用的共享索引文件，每次创建或读取基于共享索引文件的新拆分索引时，都会将它的修改时间更新为当前时间。

此缓存旨在加快涉及确定未跟踪文件的命令的速度，例如 git status。

此功能通过记录工作树目录的 mtime 来实现，然后省略读取目录和针对那些 mtime 未更改的目录中的文件的 stat 调用。为了使此功能正常工作，底层操作系统和文件系统必须在目录中添加、修改或删除文件时更改目录的 st_mtime 字段。

您可以使用 --test-untracked-cache 选项测试文件系统是否支持该功能。--untracked-cache 选项过去在旧版本的 Git 中隐式执行该测试，但现在不再是这样。

如果您想启用（或禁用）此功能，使用 core.untrackedCache 配置变量（请参阅 git-config[1]）比在每个存储库中使用 --untracked-cache 选项来运行 git update-index 更容易，尤其是在您想在所有使用的存储库中执行此操作时，因为您可以在 $HOME/.gitconfig 中将配置变量设置为 true（或 false）一次，它就会影响您访问的所有存储库。

当 core.untrackedCache 配置变量发生更改时，下次命令读取索引时，未跟踪的缓存将被添加到索引中或从索引中删除；而当使用 --[no-|force-]untracked-cache 时，未跟踪的缓存会立即被添加到索引中或从索引中删除。

在 2.17 之前，未跟踪的缓存存在一个错误，即用指向另一个目录的符号链接替换目录会导致它错误地将 Git 跟踪的文件显示为未跟踪的文件。请参阅 git.git 中的“status: add a failing test showing a core.untrackedCache bug”提交。对此的解决方法是（这可能适用于将来的其他未发现的错误）

此错误也被证明会影响将目录替换为文件的非符号链接情况，涉及未跟踪缓存的内部结构，但尚未报告任何导致“git status”输出错误的情况。

还有一些情况，即在 2.17 之前的 Git 版本中写入的现有索引将引用不再存在的目录，这可能会导致“git status”上出现许多“could not open directory”警告。这些是针对以前被静默丢弃的现有问题的新的警告。

与上面描述的错误一样，解决方法是一次性使用 core.untrackedCache=false 运行“git status”来清除遗留的错误数据。

此功能旨在加快具有大型工作目录的仓库的 Git 操作。

它使 Git 能够与文件系统监控器协同工作（参见 git-fsmonitor--daemon[1] 和 githooks[5] 中的“fsmonitor-watchman”部分），监控器可以告知 Git 哪些文件已修改。这使 Git 能够避免必须对每个文件执行 lstat() 操作来查找已修改的文件。

当与未跟踪缓存一起使用时，它可以通过避免扫描整个工作目录以查找新文件的成本，进一步提高性能。

如果要启用（或禁用）此功能，使用 core.fsmonitor 配置变量（参见 git-config[1]）比在每个仓库中使用 --fsmonitor 选项来 git update-index 更容易，特别是如果希望在所有使用的仓库中执行此操作，因为可以将配置变量在您的 $HOME/.gitconfig 中设置一次，并使其影响您接触的所有仓库。

当更改 core.fsmonitor 配置变量时，文件系统监控器将在下次命令读取索引时添加到索引或从索引中删除。当使用 --[no-]fsmonitor 时，文件系统监控器会立即添加到索引或从索引中删除。

该命令遵守 core.filemode 配置变量。如果仓库位于其可执行位不可靠的文件系统上，则应将其设置为 false（参见 git-config[1]）。这会导致命令忽略索引中记录的文件模式与文件系统上的文件模式之间的差异，如果它们仅在可执行位上有所不同。在这样的不幸的文件系统上，您可能需要使用 git update-index --chmod=。

类似地，如果 core.symlinks 配置变量设置为 false（参见 git-config[1]），符号链接将作为普通文件检出，并且此命令不会将记录的文件模式从符号链接修改为普通文件。

该命令查看 core.ignorestat 配置变量。请参见上面的“使用“假设未更改”位”部分。

该命令还查看 core.trustctime 配置变量。当 inode 更改时间定期被 Git 之外的某些内容修改时（文件系统爬虫和备份系统使用 ctime 标记已处理的文件），这将很有用（参见 git-config[1]）。

未跟踪缓存扩展可以通过 core.untrackedCache 配置变量启用（参见 git-config[1]）。

用户通常尝试使用 assume-unchanged 和 skip-worktree 位告诉 Git 忽略对已跟踪文件的更改。这不会按预期工作，因为 Git 仍然可能在执行某些操作时检查工作树文件与索引。通常，Git 不提供忽略对已跟踪文件更改的方法，因此建议使用其他解决方案。

例如，如果您要更改的文件是某种配置文件，则仓库可以包含一个示例配置文件，然后可以将其复制到忽略的名称中并进行修改。仓库甚至可以包含一个脚本，将示例文件视为模板，自动对其进行修改和复制。

git-config[1], git-add[1], git-ls-files[1]

是 git[1] 套件的一部分