Git 忽略已跟踪文件：git rm --cached 与 .gitignore 实战详解

你有过这种经历吗：项目里某个文件早就 git add 进去了，后来想让它不被 Git 继续跟踪，把它写进 .gitignore，结果发现 git status 里它该变还是变，规则根本没起作用，甚至让人怀疑是自己记错了语法。这个需求说白了就一句话：让 Git 忽略已加入的文件。它不是一类冷门操作，日常开发里几乎人人都会遇到，尤其是处理本地配置文件、编译产物、日志目录、临时脚本这一类内容。这篇文章就围绕“Git 忽略已加入的文件”展开，把原理讲清楚，把常见做法和坑都摆出来。适合对 Git 有一定基础、但还没系统处理过“已跟踪文件如何忽略”的开发者参考，当然，如果你只是被这个问题卡住，照着前面的方案操作也能很快解决。

1. 先搞懂为什么 .gitignore 会“失效”

很多人第一次撞上这个问题，第一反应是检查 .gitignore 的写法是不是有问题。实际上大部分时候语法没毛病，真正的问题在于：.gitignore 只对未跟踪文件生效。这是个非常基础、却又非常容易忽略的知识点，值得先花点篇幅讲透。

1.1 追踪与未追踪的定义

Git 对项目里的文件划分了两大阵营：已跟踪文件和未跟踪文件。已跟踪文件指那些已经被 Git 记录在索引（也就是常说的暂存区）里的文件，简单说就是至少执行过一次 git add 的文件，如果再提交过，就被永久纳入了版本历史的快照里。未跟踪文件则是项目里存在、但 Git 从未被告知要管理的文件，比如新建但还没 git add 的文件。

.gitignore 的作用机制决定了它只会过滤“未跟踪”那一侧的文件。当你写了一条规则说“忽略 config.yaml”，Git 会检查一个文件是否进入过索引：如果它从未被跟踪，那么这条规则就会拦住它，不让它出现在 git status 的未跟踪列表里；如果它已经被跟踪了，Git 根本不会拿 .gitignore 的规则去判断它，因为对一个已经纳入版本控制的文件来说，忽略规则没有优先权。

这就是“文件已经加入 Git，再写忽略规则不生效”的根源。可以类比成一个已经入职的员工，就算考勤系统里标记他“不用打卡”，他依然在公司花名册上，系统仍然能看到他的出入记录。想让他彻底不被记录，得先从花名册里摘出去，而不是只改考勤规则。

1.2 已加入文件加上 gitignore 后的行为

假设你的项目里有一个 config/app.yaml，它早就被提交到了仓库里。后来你发现这个文件在每台机器上内容可能不一样，于是打算把它忽略掉，就顺手在 .gitignore 里加了这么一行：

bash复制config/app.yaml

接下来你修改了本地的 config/app.yaml，满怀期待地认为它不会再出现在改动列表里。结果 git status 一刷：

bash复制Changes not staged for commit:
  modified:   config/app.yaml

它还在那里，清清楚楚，照常显示。还有更迷惑的情况：如果你把一个本不想添加的目录 logs/ 写进了 .gitignore，但之前手滑执行过 git add logs/，那么日志文件依然会出现在 git status 里，而且每次新增日志都会冒出来，怎么都压不住。

1.3 核心结论

面对这类情况，唯一的思路是：先改变文件的跟踪状态，再配合 .gitignore 规则。具体来说有两种路线：

• 让 Git 停止跟踪这个文件，但本地文件保留。这是最主流的做法，适合那些“要本地存在、但每个环境内容不同”的文件。
• 让 Git 继续跟踪文件，但假装看不到它的本地变化。这类做法适合“文件必须保留在仓库中，但本地不希望每次改动都出现在 status 里”的情况。

两条路线各有适用场景，下面分别展开。

2. 最常用的正解：从暂存区移除，保留工作区文件

终止 Git 对某个文件的跟踪，核心命令是 git rm --cached。关键在于 --cached 这个参数，它的意思是“只移除索引里的记录，不删除工作区里的物理文件”。如果漏掉这个参数直接执行 git rm，本地文件也会被删掉，那就不是忽略文件而是删除文件了，这个区别一定要记牢。

2.1 单文件处理流程

以 config/app.yaml 为例，完整操作如下：

bash复制git rm --cached config/app.yaml

执行完以后，Git 会把这个文件的删除操作暂存起来。注意，这个过程中工作区里的 config/app.yaml 还好好地躺在那里，没有任何改动。接着运行 git status，你会看到类似这样的输出：

bash复制Changes to be committed:
  deleted:    config/app.yaml

此时不要慌，文件并没有真的消失，这只是 Git 在告诉你“我准备把它从版本控制里去掉了”。然后立刻把它加进 .gitignore：

bash复制echo "config/app.yaml" >> .gitignore
git add .gitignore

最后提交这次变更：

bash复制git commit -m "chore: 停止跟踪 config/app.yaml"

提交完成之后，这个文件就正式从版本控制里消失了，但本地磁盘上依然存在。之后再怎么修改它，git status 都不会再显示它，彻底安静了。

这里有一个很容易踩的节奏问题：执行完 git rm --cached 之后要马上把 .gitignore 的规则补上并提交。如果中间间隔太久，你改了本地文件，那么它一边会被标记为“已暂存的删除”，一边又会以未跟踪文件的形式冒出来。更尴尬的是，如果这时候 .gitignore 还没写，它就会同时出现删除暂存和新的未跟踪文件，整个 status 看上去又乱又吓人，但实际修复很简单：补上 .gitignore 规则，再正常提交就行。

2.2 批量处理目录

如果之前不小心把一个整个目录都 git add 进去了，比如 logs/，那就不能用单文件的命令一个个删了，得加上 -r 参数：

bash复制git rm -r --cached logs/

--cached 保证本地 logs/ 目录及其内容都不会被删除，而 -r 让 Git 递归处理目录里的所有子文件和子目录。执行完同样把 logs/ 写进 .gitignore，然后提交。

批量操作最大的好处是可以一次性把误跟踪的目录清干净。我遇到过一种情况：项目构建脚本每次运行都会生成一堆临时文件到 build/ 目录，有人刚开始不理解，直接 git add . 把整个 build/ 带进了仓库，结果后面每次构建都会产生一堆未跟踪文件，仓库也变得臃肿。处理办法就是用上面这条命令把 build/ 从索引里剔除，再让 .gitignore 接管，后续构建过程就再也不会污染 git status 了。

2.3 没有提交过只是 add 过的情况

如果文件并不是从历史提交中带入的，只是你刚执行了 git add，但还没 git commit，那么更简单的方案是撤销暂存：

bash复制git reset HEAD config/app.yaml

或者如果这个文件本身就是新建的、还不曾提交过，用 git rm --cached 也一样能达到目的。区别在于，git reset HEAD 更适合“暂存区里放多了文件，想退回未跟踪状态”的场景，它会把暂存区还原，文件回到工作区里，同时保持未被跟踪的初始状态。此时文件会重新出现在未跟踪列表里，后续靠 .gitignore 拦截即可。

2.4 注意事项

用 git rm --cached 时有几个必须留意的地方：

• 只要加了 --cached，本地文件就安全。不加 --cached，是真正的物理删除，慎用。
• git rm --cached 之后，这个文件的删除会被纳入下一次提交。如果不做这次提交，远端的仓库里文件还在，团队其他人拉代码时，文件依然会被跟踪。
• 提交之前，确认 .gitignore 已经写好了忽略规则，否则下一次 git status 会看到它变成未跟踪文件，又会被提醒添加。
• 如果你的配置文件本来是团队共享的基础配置，把它从跟踪列表移除后，别人新克隆仓库时就不会自动获得这个文件，需要考虑是否提供 .example 模板。

实际操作中，我不建议把重要配置一股脑全忽略掉。比如项目启动必需的 config.yaml，如果仓库里完全没有样本，新成员拉代码后会一脸懵，不知道该怎么创建这个文件。更好的做法是保留一个 config.yaml.example，在 README 里写清楚“复制一份并按需修改”，同时把 config.yaml 加入忽略。这属于团队协作里很常见的配套习惯，后面第四部分还会细说。

3. 进阶方案：保留追踪但让 Git 忽略本地变化

有时候你不能简单地把文件移出版本控制。比如项目里有一份 version.txt，每次构建都会自动改写，但它又需要留在仓库里作为版本基准；再比如某些带状态缓存功能的配置文件，团队共享一套默认值，但本地运行时会自己改内容。这时候如果贸然用 git rm --cached 移除跟踪，会让团队所有人丢失这个文件的仓库版本，可能引发连锁问题。

Git 提供了一组更精细的命令，让你在“保留跟踪”的前提下，告诉 Git“别管这个文件了”。这就是 git update-index 家族的几个标志位。

3.1 两个命令的差异

第一个是 --assume-unchanged：

bash复制git update-index --assume-unchanged path/to/file

这个选项是告诉 Git：请假定这个文件没有变化，别再花精力检查它。它本来是为性能设计的，主要场景是当仓库里有大量体积较大、内容不变的大文件时，减少 Git 不必要的哈希校验。

第二个是 --skip-worktree：

bash复制git update-index --skip-worktree path/to/file

这个标志位更贴近“本地配置不想被提交”的意图。它告诉 Git：这个文件在索引里存在，但工作区的改动请你完全跳过，只有在特定的强制操作下才处理它。从语义上讲，--skip-worktree 更适合“本地个性化修改但不想提交”的场景，而 --assume-unchanged 更偏向“文件内容不该变，别浪费时间检查”。现在很多团队里遇到“本地保留配置、但不能误提交”的需求，推荐优先考虑 --skip-worktree。

3.2 适用场景

我举一个真实遇到过的例子。某项目的 application.yml 里默认配置指向测试环境，但它又会读取本机环境变量覆盖部分参数。每次本地启动后，这个文件都会因为环境变量替换而改变，导致 git status 里永远飘着一个 modified。用 git update-index --skip-worktree application.yml 标记后，状态立刻清爽，文件该被本地程序改还是照常改，只是 Git 不再过问。

这个方案的巨大好处是：团队其他人拉代码时，依然可以从仓库拿到 application.yml 的默认版本，文件不会丢失；你本地的个性化修改也不会被提交，不会把本地数据库地址之类的东西推到远端。

3.3 注意事项和坑

--skip-worktree 并不是完美方案，踩坑的概率也不小。最大的问题是标记状态存在本地的索引文件中，它不会随着提交传给远端。同一份仓库换一台机器或者重新克隆后，这个标记就失效了，你得重新执行一次命令。所以如果有多个环境、多台机器，建议写一个初始化脚本，把需要标记的文件统一跑一遍。

还有个更微妙的坑：当你在标记了 --skip-worktree 的文件所在的分支上执行分支切换时，如果目标分支对这个文件有内容更新，Git 可能会因为索引与工作区不一致而报出奇怪的错误。最典型的情况就是 merge 或 checkout 时提示文件被本地修改，但实际上你根本没动过它。处理这种状况时，得先把 --skip-worktree 标志取消，让 Git 重新检查文件状态，再执行分支操作。

另外，如果某个文件既被 --skip-worktree 标记，又出现在 .gitignore 规则里，依然不能让它从跟踪列表里消失或阻止历史中的更新，因为 .gitignore 对它已经彻底不适用了。这种组合不会带来额外帮助，反而会让排查问题的人更困惑。

3.4 查看与恢复

想知道当前哪些文件被标记了，可以用：

bash复制git ls-files -v

查看标记状态。想要恢复对文件的正常跟踪，分别用对应的反向参数：

bash复制git update-index --no-skip-worktree path/to/file
git update-index --no-assume-unchanged path/to/file

执行完之后，git status 会立即重新显示文件的变化。因此我的建议是：--skip-worktree 只用来处理“本地个性化但绝不能提交”的文件，不要滥用，更不要拿它替代“应该彻底移除跟踪”的场景。数量少的时候维护成本不高，一旦文件多了，你的 Git 索引状态会越来越混乱，新接手的人很难理解这些文件的真实状态。

4. 让 .gitignore 规则写得更稳

前两节讲了如何改变跟踪状态，这一节再把 .gitignore 本身那些容易出错的语法和场景集中过一遍。很多人第一次写忽略规则时，喜欢凭感觉写，写出来的规则确实也生效，但等到规则多了、团队大了，你就会发现细节决定成败。

4.1 基本语法

.gitignore 并不是特别复杂的匹配系统，但也不是一把梭的通配符。

• 每一行一条规则，# 开头的是注释。
• / 开头表示从仓库根目录开始匹配，比如 /target 只匹配根目录下的 target，不会匹配 src/target。
• 结尾的 / 表示目录，比如 build/ 匹配任意层级的名为 build 的目录。
• * 可以匹配任意字符，但不跨目录分隔符。*.log 能匹配 app.log，也能匹配 logs/app.log，但它无法匹配 logs/sub/app.log，如果希望任意层级匹配，需要写成 **/*.log 或直接 *.log 也行？这里有个细节，Git 的 *.log 实际上可以匹配任意层级的文件，因为这种不带 / 的模式按规律会匹配路径的任意部分。而 doc/*.txt 这类带一个目录分隔符的模式，则只匹配 doc 下一层的 .txt 文件。
• ? 匹配单个字符。
• ! 用在规则开头，表示排除忽略。例如 *.log 忽略所有日志，但 !important.log 保留重要的那个。注意，排除一个文件的前提是它的父目录没有被彻底忽略，否则 Git 根本看不到这个文件，排除规则也不起作用。

这最后一点是真正的隐藏坑。很多人写了类似于“忽略 build 目录，但保留 build/ci/release.json”的规则，结果发现 release.json 始终不出现。原因就是 build/ci 整个被忽略了，Git 不会进入这个目录去发现你那个 !build/ci/release.json 规则。解决方法通常是：先不完全忽略父目录，而是用 * 配合 !，或者干脆把父目录的忽略粒度收窄。比如这么写：

bash复制build/*
!build/ci/
build/ci/*
!build/ci/release.json

但说老实话，这种写法已经比较复杂了，日常项目里如果真遇到这种需求，我更建议重新考虑一下目录结构，把需要保留的东西从被忽略的目录里移出去，而不是和规则较劲。

4.2 常见配置样例

下面是一个比较实用的 .gitignore 片段组合：

bash复制# 编译产物
dist/
build/
*.class

# 日志
*.log
logs/

# 本地配置
config/app.local.yaml
.env
!.env.example

# 系统文件
.DS_Store
Thumbs.db

# IDE 配置
.idea/
.vscode/

注意看 .env 和 !.env.example 的组合。.env 是本地敏感配置，必须忽略；.env.example 是提交到仓库的模板，不能忽略。这种“模板文件入库、真实文件忽略”的思路，在前后端项目里都很有用。

4.3 强制添加与反向排除

即便文件已经在 .gitignore 里，你还是可以强行把它加入仓库，命令是：

bash复制git add -f config/app.yaml

-f 是 --force 的缩写，表示忽略 .gitignore 的限制，强制跟踪这个文件。这个命令偶尔用来纠正误加忽略规则的情况，但日常不建议频繁使用。它相当于你明确告诉 Git：这条规则对我来说可以例外。一旦你 add -f 之后，这个文件就变成已跟踪状态了，规则自然又失效了，下次想忽略它还得再走一遍 git rm --cached 的流程，等于绕了一圈。

相对应的，反向排除更多是“写规则时”的事，比如这样一组规则：

bash复制*.js
!custom.js

custom.js 会重新被纳入跟踪，只要它的父目录没有被完全忽略。

4.4 团队协作配套

当你要把一个原本受版本控制的文件改成忽略时，光自己本地操作还不够，团队协作层面也得跟上。

最典型的场景是这样的：我对 config/app.yaml 执行了 git rm --cached，然后 push 到远端。同事 pull 之后发现仓库里这个文件还在他本地磁盘上，但不会再进入提交列表。如果同事不知道这个变化，他可能继续在里面修改本地配置，然后提交，结果提交时发现列表里没有它，会以为 Git 出 bug 了，或者在 review 时产生困惑。

所以比较好的做法是，在 commit message 里写清楚这次变更是“停止跟踪 config/app.yaml，本地配置改为手动维护”，同时在 README 或团队文档里补充说明。如果项目里有 config/app.yaml.example 模板文件，更应该顺手说明“请复制为 config/app.yaml 并按需修改”。这样可以最大程度减少新成员和同事踩到同样的坑。

5. 常见问题与排查技巧实录

处理“Git 忽略已加入的文件”这块内容，实际操作中会遇到不少看起来像是规则错误、实际上另有原因的问题。整理一份速查表，再配合几个真实踩坑经历，能帮你更快定位问题。

5.1 问题速查表

下面整理了我见过最多的问题和对应解法：

这张表里的多数问题都指向同一个核心认知：区分文件是否已被跟踪，是理解所有 Git 忽略问题的总开关。

5.2 几个我踩过的坑

第一个坑是批量删除时手抖。有一次我负责清理项目里反复出现的构建产物目录，打命令时脑子里想着 git rm --cached build/，结果脑子里想着 --cached，手却少敲了，执行了 git rm -r build/。只看到屏幕上一闪而过一堆 deleted，当时心里就咯噔一下，切回工作区一看，本地目录已经空了。好在当时是构建产物，重新构建就能恢复，但要是换成一个重要配置，损失就大了。所以这里要再次强调：针对目录或文件做批量操作时，第一眼先确认命令行里有没有 --cached，这句话重复多少遍都不过分。

第二个坑是团队协作时队友在 status 里发现文件被标记为 “deleted” 后，下意识地在 IDE 里选择了“恢复删除”。结果就是把一个已经决定要忽略的文件又拉了回来，而且很可能连同他本地的个性化内容一起重新进入了暂存区，最后形成一场混乱的合并。这提醒我，当你的变更涉及“让某文件不再被跟踪”时，尽量在提交信息里字面写明意图，最好带着 MM 号或者需求单号，让同事点开提交记录就能明白这不是误删。

第三个坑和 .gitignore 规则本身有关。我给某项目写了一个 *.cache/ 规则，原本只希望忽略 cache 目录，结果后面新增了一个名字带 .cache 后缀的文件时，也被一起忽略了。排查了半天才发现 *.cache/ 这种写法其实匹配了文件名以 .cache 结尾的任何条目，包括文件。所以写规则时，目录确定就用结尾的 / 限定，谨慎使用带通配符的目录形式。

6. 从“会操作”到“用得顺”的几条建议

聊到这里，命令层面的东西已经说得比较全了。最后想分享一些偏“项目习惯”上的经验。毕竟“让 Git 忽略已加入的文件”不是解决一次就完事，更像是一个需要长期维护的工程习惯。

第一个建议是：把“哪些文件应该被忽略、哪些文件必须入库”当成项目配置的一部分来管理。我习惯在项目根目录放一个 .gitignore，同时把 README 的“开发环境准备”小节写清楚，里面包含文件模板的复制命令。比如前端项目常见这样一段说明：

bash复制cp .env.example .env
npm install
npm run dev

后端项目则类似：

bash复制cp config/app.yaml.example config/app.yaml

这样新成员克隆代码后，第一步就知道要生成哪个本地文件，绝不会因为缺少被忽略的配置而卡住。

第二个建议是：定期扫一眼 .gitignore 的规则，删除过时的，补充新出现的。项目发展到一定阶段，旧规则常常保留了很多已经不需要忽略的路径，比如某个目录早就从项目里删掉了，但规则还在，看着碍眼，还会误导人。可以用 git check-ignore -v 查看某个文件具体是被哪条规则命中的，排查起来很方便。比如想知道 config/app.yaml 是否真的被忽略，可以：

bash复制git check-ignore -v config/app.yaml

如果输出里有规则路径和行号，说明它确实处于忽略状态；如果没输出，则说明这条文件并没有被忽略规则覆盖到。同理，git status --ignored 可以列出当前所有被忽略的文件，定期看一眼，有助于保持规则清爽。

第三个建议是区分“真正应该忽略”和“暂时不想看到变化”两类需求。很多人纠结于 --skip-worktree 和 git rm --cached 怎么选，其实就是没想清楚自己的文件到底是什么定位。如果这个文件必须在仓库里作为团队共享基准，只是本地方便起见不想显示变化，那就用 --skip-worktree。如果这个文件本来就应该由本地环境自行维护，仓库里根本不应该存在它的实际内容，那就痛快点，直接 git rm --cached 加 .gitignore，别让文件的历史继续留在版本控制快照里。这个判断一旦想明白，后面动作自然就清晰了。

我个人在实际操作中的体会是，让 Git 忽略已加入的文件这件事，本身不难，难的是做决定前先想清楚“这个文件在团队协作里的定位是什么”。想清楚之后，是走 git rm --cached 还是 git update-index --skip-worktree，用一条命令还是两条命令，心里都有数，处理起来也不容易留下后遗症。最后再说一个能让你省心的小技巧：如果公司项目里经常要处理这类本地配置文件的忽略，可以在 Git 全局配置里加个别名，自定义一个命令，比如在命令行里输入：

bash复制git config --global alias.ignore-keep '!git rm --cached'

平时用 git ignore-keep config/app.yaml 就能完成移除跟踪的操作，少打几个参数，也就少一分误删的风险。当然，这只是个锦上添花的习惯，真正重要的还是底层那套“先理解跟踪状态，再选择对应命令”的思路，希望这篇内容能帮你彻底理清。