git filter-branch显示已删除文件但实际未删除的问题

我之前也踩过这个filter-branch的坑！明明命令输出看起来都执行了，但文件一点没动，大概率是命令参数或者路径列表的细节没做好，咱们一步步来解决：

可能的问题点&修复方案 #

1. 路径列表格式不对 #

你创建的路径列表一定要注意这几点：

• 所有路径都是相对于仓库根目录的，不能用绝对路径或者相对当前目录的路径
• 大小写敏感！比如你的仓库里是src/Utils.js，列表里写src/utils.js就会匹配失败
• 如果要保留整个目录，路径末尾可以加斜杠（比如src/core/），但不加也能生效，不过统一格式更稳妥

2. filter-branch命令参数写错/顺序错了 #

你可能没在--index-filter里写对删除逻辑，或者参数顺序不对。正确的命令应该是这样的：

# 先确保工作区干净，避免干扰
git stash

# 执行filter-branch，注意参数顺序：--prune-empty要在--index-filter前面
git filter-branch --prune-empty --index-filter 'git rm --cached -r --ignore-unmatch $(cat 你的路径列表文件名.txt || echo "")' HEAD

这里几个关键参数的作用：

• --cached：只操作Git索引，不删除本地工作区文件（后续可以用git reset --hard同步工作区）
• -r：递归删除目录下的所有文件
• --ignore-unmatch：如果列表里的路径不存在，命令不会直接失败，会继续执行
• || echo ""：防止路径列表为空时命令报错

3. 你在错误的分支上操作了？ #

执行命令前先确认当前分支是不是你要处理的分支：git branch，如果不是，切换到目标分支再执行。

4. 试试更可靠的替代工具：git filter-repo #

Git官方已经不推荐用filter-branch了，它有很多已知的bug和性能问题，更推荐用git filter-repo（大部分新版Git已经自带，若没有可自行安装）。用它处理的话命令更简单，也不容易出问题：

git filter-repo --path-from-file 你的路径列表文件名.txt

执行完这个命令，不需要额外操作，所有非列表里的文件都会被彻底移除，无关的提交也会被清理掉。

重要提醒 #

不管用哪种方法，操作前一定要备份整个仓库！比如复制一份仓库文件夹，或者把当前分支推送到一个临时远程仓库，万一操作失误还能恢复。

内容的提问来源于stack exchange，提问作者Guenther Brunthaler