git filter-branch 已被弃用，应改用 git rebase -i（小范围）或 git filter-repo（大规模），后者是官方推荐替代工具，安全高效且无残留；重写历史后需用 --force-with-lease 推送并同步团队。
filter-branch 已被弃用，别再用它改提交信息
Git 官方在 2.22 版本起明确标记 git filter-branch 为“deprecated”，后续版本中警告越来越频繁，2.39+ 会直接报错。它不仅慢、易出错，还可能破坏 reflog、丢失合并提交结构，甚至损坏子模块引用。
真正该用的是 git rebase -i（小范围）或 git filter-repo（大规模、安全、快）——后者是官方推荐的替代工具，由原 filter-branch 维护者亲自开发。
用 git rebase -i 修改最近几次提交信息
适合改最近 3～10 次提交，交互清晰、风险可控，不碰历史深层结构。
- 运行
git rebase -i HEAD~5（改最近 5 次）；编辑器里把想改的行前的pick改成reword - 保存退出后，Git 会逐个打开每个提交的编辑器，让你重写
commit message - 改完保存，Git 自动重放提交。注意：所有后续提交的 SHA 都会变，如果已推送到远程，需强制推送：
git push --force-with-lease - 别对已公开共享的分支滥用——协作中强制推送会打乱他人本地历史
用 git filter-repo 批量重写全部历史中的提交信息
要改几百次提交、或匹配特定作者/日期/关键词批量替换，git filter-repo 是唯一靠谱选择。它基于 Python，单线程但高效，且默认保留原始时间戳、签名和合并关系。
- 先安装：
pip install git-filter-repo（别用apt或brew装旧版） - 备份当前分支：
git branch backup-before-filter（这步不能省） - 把所有 “old@example.com” 提交作者名替换成 “New Name”：
git filter-repo --mailmap <code>mailmap.txt，其中mailmap.txt写成New Name <new> old@example.com</new> - 只改提交信息正文（不含作者/时间）：
git filter-repo --message-callback 'return msg.replace(b"TODO:", b"FIXED:")' --force - 执行后自动清理 refs，不会残留
refs/original/这类危险残留（而filter-branch会留一堆，不手动删可能意外恢复错误历史）
改完必须同步远程，但 force-push 有讲究
无论用哪种方式重写历史，远程仓库不会自动更新。强制推送不是加个 --force 就完事。
- 优先用
git push --force-with-lease，它会检查远程最新提交是否仍是自己知道的那一个，避免覆盖别人新推的内容 - 如果团队共用分支，必须提前通知所有人：停止推送、拉取、基于旧历史做操作；等你推完，他们得用
git fetch && git reset --hard origin/main重置本地分支（不能pull，会引入重复提交） - GitHub/GitLab 上已有的 PR、CI 记录、issue 关联都会断开——因为提交 SHA 全变了。这不是 bug，是重写历史的必然代价
最麻烦的从来不是命令怎么敲，而是谁还在基于旧 SHA 做事、CI 是否缓存了旧对象、是否有钩子脚本硬编码了某个提交哈希——这些细节，比选对工具更难排查。
