Git update-index 怎样恢复被忽略的文件变化

Git 跟踪的文件明明改过，git status 和 git diff 却没有变化，先不要急着重新克隆仓库。文件可能被 Git 的索引标记设置成了“假定未变化”或“跳过工作区”，这和 .gitignore 不是一回事。

官方地址：https://git-scm.com/docs/git-update-index

处理顺序很简单：先用 git ls-files -v 看标记，再用对应的 git update-index --no-... 清除，最后重新查看差异。下面以一个虚构的 app/config.yaml 为例，界面图片均为原创操作说明图，不是 Git 客户端实际截图。

先确认 Git 把文件标记成了什么

在仓库根目录打开命令行，或者在你常用的 Git 图形工具中进入文件状态面板。重点不是盯着“没有修改”这个结果，而是确认索引是否保存了特殊标记。

# 只查看目标文件的索引标记，避免先改动工作区
git ls-files -v -- app/config.yaml

# 查看整个仓库中带有特殊状态的跟踪文件
git ls-files -v | sed -n 's/^[a-z?] //p'

不同 Git 版本和客户端对状态字母的展示可能略有差异，但如果目标文件被标成小写状态，通常值得继续检查。assume-unchanged 的含义是 Git 暂时相信工作区文件没有变化；skip-worktree 更偏向稀疏工作区，表示 Git 在合理情况下不要把该路径写回工作区。

清除 assume-unchanged 标记

如果文件实际在工作区中存在，只是修改后没有出现在差异列表，优先清除 assume-unchanged。官方文档明确提供了成对的 --assume-unchanged 和 --no-assume-unchanged 参数，后者用于恢复正常检查。

# 让 Git 重新检查这个已跟踪文件的工作区变化
git update-index --no-assume-unchanged -- app/config.yaml

# 立即查看文件是否重新出现在工作区差异中
git status --short -- app/config.yaml
git diff -- app/config.yaml

如果这时出现 M app/config.yaml，说明文件修改已经重新被 Git 识别。这里的命令不会覆盖文件内容，也不会自动提交；它只改变索引对该路径的检查方式。

如果是 skip-worktree，使用对应的恢复参数

另一种情况是仓库启用了稀疏检出，或者有人直接对路径设置了 skip-worktree。这时不要继续重复执行 --no-assume-unchanged，应清除另一种标记。

# 清除 skip-worktree，让目标路径回到普通工作区检查
git update-index --no-skip-worktree -- app/config.yaml

# 重新列出状态，确认路径不再被稀疏标记遮住
git ls-files -v -- app/config.yaml
git status --short -- app/config.yaml

Git 官方把 skip-worktree 主要用于稀疏检出：文件可以不出现在工作区，且缺失不应被当成删除。若你的真实目标是只保留仓库的一部分，长期方案应使用 git sparse-checkout，不要把低层的 update-index 当成普通忽略开关。

相关地址：https://git-scm.com/docs/sparse-checkout

清除标记后怎样确认恢复成功

1. 用 git ls-files -v -- 路径 再看一次状态，确认不再显示原来的特殊标记。
2. 用 git status --short -- 路径 查看文件是否回到普通修改状态。
3. 用 git diff -- 路径 确认差异内容确实是你刚才的改动。
4. 如果文件曾经被稀疏检出隐藏，确认它已经回到工作区，再决定是否继续使用稀疏检出。

如果仍然没有变化，检查目标文件是否真的是已跟踪文件、是否修改了另一个同名路径，以及是否有脚本在命令执行后再次设置索引标记。不要把“恢复可见”误解为“自动提交”；提交仍然需要正常执行 git add 和 git commit。

常见问题

这和 .gitignore 有什么区别？

.gitignore 主要影响未跟踪文件是否出现在候选列表中；本文的两个标记作用在已经被 Git 跟踪的路径上。已跟踪文件突然不出现在差异里，优先检查索引标记。

能不能用 update-index 永久忽略配置文件？

不建议把它当作永久忽略方案。assume-unchanged 只是让 Git 假定文件未变化，后续合并或索引更新仍可能暴露问题；团队共享的忽略规则应使用合适的忽略文件或模板。

什么时候该用 sparse-checkout？

当目标是大型仓库只保留部分目录时，使用 git sparse-checkout set 管理范围更清晰。只有在排查已有索引标记、需要恢复单个路径时，才直接使用 update-index。

最后确认

文件变化看不到时，先确认它是被 assume-unchanged 还是 skip-worktree 标记影响，再分别执行 --no-assume-unchanged 或 --no-skip-worktree。最后用 git status 和 git diff 双重确认；如果要管理整套稀疏工作区，则切换到 sparse-checkout。