Git 文件忽略备忘录：`assume-unchanged` 完全指南

不改动 .gitignore，让 Git 对某些文件“视而不见”

这命令是干嘛的？

你是否有过这样的经历：项目里有个配置文件（比如 application.yml 或 .env），每个人本地都要改，但谁都不想把它提交到远程仓库？

.gitignore 只能忽略尚未被跟踪的文件。一旦文件被提交过，.gitignore 就对它无能为力了。

这时候，git update-index --assume-unchanged 就是你的救星。它的作用是告诉 Git：

“这个文件我承诺不会修改它，你就当它没变过吧。”

于是 Git 便不再检查这个文件的状态，git status 里再也看不到它的变化。

注意：这个标记是本地的，只存在于你机器的 .git 目录中，不会同步到远程仓库。每台机器可以独立决定是否忽略某个文件。

一、添加忽略（让 Git 假装看不见）

git update-index --assume-unchanged <文件路径>

示例：

# 忽略单个文件
git update-index --assume-unchanged config/database.yml

# 忽略整个文件夹（注意：文件夹名后面要加 /）
git update-index --assume-unchanged logs/

# 忽略文件夹下所有 .log 文件
git update-index --assume-unchanged logs/*.log

⚠️ 踩坑提醒：忽略文件夹时，路径末尾一定要加 /，否则会报错！

二、查看忽略列表（看看哪些文件被“雪藏”了）

# 查看所有文件的标记状态
git ls-files -v

输出的每一行开头都有一个字母标识：

标识	含义
H	正常跟踪的文件
h	已设置 assume-unchanged（你要找的！）
S	已设置 skip-worktree
M	未合并
R	已删除
C	已修改
?	其他忽略文件

只看被忽略的文件：

# 只列出 assume-unchanged 的文件
git ls-files -v | grep '^h'

# 只提取文件路径（去掉前面的标识符）
git ls-files -v | grep '^h' | awk '{print $2}'

三、取消忽略（让 Git 重新“看见”文件）

git update-index --no-assume-unchanged <文件路径>

示例：

# 取消单个文件的忽略
git update-index --no-assume-unchanged config/database.yml

批量取消所有忽略（一键恢复）：

git ls-files -v | grep '^h' | awk '{print $2}' | xargs git update-index --no-assume-unchanged

这条命令会：找出所有被忽略的文件 → 提取路径 → 批量取消忽略。

四、⚠️ 重要警告（不看会后悔）

1. 这玩意不是用来“永久忽略”的

--assume-unchanged 的本意是性能优化——当文件系统很慢（比如 CIFS 网络挂载）时，让 Git 跳过对某些文件的检查。它不是设计用来永久忽略文件修改的。

2. 切换分支时可能丢改动

如果你在分支 A 忽略了某个文件，然后切换到分支 B——而分支 B 里这个文件的内容不同——Git 可能会直接覆盖你的本地修改，导致改动丢失。

3. 远程有更新时可能合并失败

如果远程仓库的这个文件发生了变更，git pull 时可能会产生冲突，或者你的本地改动无法推送。

4. 别人依然能看到你的修改

这个标记是本地的，不影响其他人。如果你 git add . 时不小心，依然可能把修改提交上去。

五、补充：assume-unchanged vs skip-worktree

这两个命令经常被混淆。简单来说：

	--assume-unchanged	--skip-worktree
设计目的	性能优化（跳过文件检查）	永久忽略本地修改
适用场景	文件系统慢、大项目	配置文件本地定制
风险	切换分支可能丢改动	更安全，Git 会保护你的本地版本

一句话建议：如果你只是想本地改配置文件而不提交，用 --skip-worktree 更安全。--assume-unchanged 更适合“这个文件真的不会改，别浪费时间检查它”的场景。

快速参考卡片

操作	命令
添加忽略	git update-index --assume-unchanged <文件>
取消忽略	git update-index --no-assume-unchanged <文件>
查看所有标记	git ls-files -v
只看被忽略的	git ls-files -v | grep '^h'
批量取消忽略	git ls-files -v | grep '^h' | awk '{print $2}' | xargs git update-index --no-assume-unchanged

---

记住：这只是个“临时失忆”小技巧，别把它当成 .gitignore 的替代品。用对了是神器，用错了是炸弹 💣