git rm 把「从磁盘删文件」和「把删除写进暂存区」合成一步。它最有用的参数其实是 --cached——只从仓库移除、保留本地文件,是修正「不小心提交了本地配置」的标准做法。

本文列出 git rm 的常用参数,并给出配合 .gitignore 清理误提交文件的完整流程。

ℹ️
关于本系列
本文是《Git 使用教程》按命令拆分的第 16 / 28 篇,全部收录在 Git 栏目。参数表列的是日常高频项,并非穷举;想看某个命令的完整参数,用 git rm -h 看精简列表、git help rm 看完整手册。示例以 Git 2.56.0 为准。

一、命令语法

先看语法骨架,再对照下一节的参数表。<占位> 表示必填值,实际输入时不要带尖括号;[...] 表示可选项,-- 用来分隔选项与路径。

bash语法
git rm [<options>] [--] <file>...

二、参数逐项详解

下表按用途列出 git rm 的常用参数,每项都注明了「它到底改变了什么」。

参数作用
--cached只从索引移除、保留磁盘文件;把文件改成忽略时用
-r递归删除目录(删目录时必加)
-f / --force强制删除;文件有未提交改动时 Git 默认会拒绝,避免误删
-n / --dry-run只演练,打印会被删的文件
-q / --quiet静默
--ignore-unmatch路径不存在时也不报错,脚本里常用
--pathspec-from-file=<文件>从文件读取路径列表,配合 --pathspec-file-nul 处理特殊文件名
--分隔选项与路径,文件名以 - 开头时必须用

三、常用示例

把误提交的本地配置移出仓库

bash把误提交的本地配置移出仓库
echo "config/local.php" >> .gitignore
git rm --cached -r config/local.php
git add .gitignore
git commit -m "chore: 忽略本地配置"
git status -sb                 # 文件还在磁盘上,只是不再被跟踪

正常删除文件与目录

bash正常删除文件与目录
git rm src/legacy.js
git rm -r old-module/
git rm -n src/tmp.js           # 先看看

批量清理

bash批量清理
git rm --cached -r --ignore-unmatch .env.local
git rm --pathspec-from-file=to-delete.txt

四、注意事项

直接用 rm 也可以: 用系统 rm 删掉文件后,Git 会记为「未暂存的删除」,再 git add -A 即可。git rm 只是把这两步合成一步,语义上没有区别。
⚠️
.gitignore 对已跟踪文件无效
把路径加进 .gitignore 不会让已经提交的文件消失,必须 git rm --cached <file> 并提交。注意这个操作会让其它协作者在下次 pull 时本地文件被删除,涉及共享配置时先沟通。

五、小结

日常真正高频的只有 git rm <file> 和 git rm --cached -r <path>。后者是「把文件从版本控制里摘出去」的唯一正确姿势,配合 .gitignore 使用,别再靠 git add -f 硬提交了。

本系列共 28 篇,一个命令一篇,完整目录见 Git 栏目。下一篇:git mv 命令参数详解。