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）来工作，然后省略读取那些修改时间未更改的目录以及对其中文件的 stat 调用。为此，底层操作系统和文件系统必须在目录中添加、修改或删除文件时更改目录的 st_mtime 字段。

你可以使用 --test-untracked-cache 选项测试文件系统是否支持此功能。在旧版本的 Git 中，--untracked-cache 选项曾隐式执行此测试，但现在已不再如此。

如果你想启用（或禁用）此功能，使用 core.untrackedCache 配置变量（参见 git-config[1]）比在每个仓库中使用 git update-index 的 --untracked-cache 选项更容易，特别是如果你想在你使用的所有仓库中这样做，因为你可以在你的 $HOME/.gitconfig 中只设置一次此配置变量为 true（或 false），它就会影响你操作的所有仓库。

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

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

当涉及未跟踪缓存的内部结构时，此 bug 也已被证明会影响非符号链接情况下用文件替换目录的情况，但尚未报告因此导致错误的“git status”输出的案例。

还有一些情况，由 2.17 之前 Git 版本写入的现有索引会引用不再存在的目录，这可能导致在“git status”上打印许多“无法打开目录”警告。这些是针对现有问题的新警告，这些问题以前被静默丢弃了。

与上述 bug 一样，解决方案是临时运行一次 core.untrackedCache=false 的“git status”以清除残留的错误数据。

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

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

当与未跟踪缓存结合使用时，它可以避免扫描整个工作目录以查找新文件的开销，从而进一步提高性能。

如果你想启用（或禁用）此功能，使用 core.fsmonitor 配置变量（参见 git-config[1]）比在每个仓库中使用 git update-index 的 --fsmonitor 选项更容易，特别是如果你想在你使用的所有仓库中这样做，因为你可以在你的 $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] 套件的一部分