git filter-branch 已被弃用，应改用 git filter-repo；C++ 项目需同步重命名文件与 #include 路径、更新 CMake 配置、备份验证编译、团队统一迁移到新历史。
git filter-branch 已被弃用，别再用它重写 C++ 项目历史
Git 官方在 2.22 版本（2019 年）起就标记 git filter-branch 为“deprecated”，2.38+ 版本开始默认禁用。它对 C++ 项目尤其危险：路径含空格、中文、符号的头文件（比如 include/utils/HTTP-Client.hpp）极易因 shell 解析失败导致重写中断或文件丢失；更严重的是，它不校验 C++ 源码中 #include 路径是否同步更新——改了文件位置却漏改 #include "old/path.h"，编译直接报错。
用 git filter-repo 替代，C++ 项目需额外处理 include 路径
git filter-repo 是当前唯一推荐的替代方案，Python 编写、速度快、安全性高，且原生支持 --path-rename 和 --subdirectory-filter。但 C++ 项目不能只靠重命名文件——头文件引用必须一并修正，否则历史提交里全是编译失败的记录。
- 先安装：
pip install git-filter-repo - 重命名目录并修正所有
#include行：git filter-repo --path-rename src/:lib/ \ --mailmap .mailmap \ --replace-text <(echo 's|#include ["<]old/|&#include ["<]lib/|g')
- 注意
--replace-text中的&是 bash 转义，实际要写成\&或换用单引号避免冲突 - 若项目用 CMake，还需同步替换
target_include_directories和include_directories中的旧路径
重写历史前必须备份，C++ 项目更要验证编译链路
filter-repo 不会保留原分支，所有重写操作都生成全新 commit hash。一旦出错，git reflog 无法找回旧历史——因为 filter-repo 默认清空 reflog。
- 执行前务必：
git branch backup-before-filter - 重写后不要直接 push，先 checkout 到新历史，用原始构建命令验证：
cmake -B build && cmake --build build - 特别检查预编译头（
stdafx.h或pch.h）、模块接口文件（module.modulemap）是否路径失效 - CI 流水线里若有缓存的 build artifacts，需强制清理，否则可能复用旧 object 文件导致链接错误
多人协作项目重写历史等于集体重置，C++ 团队要同步动作
C++ 项目通常依赖稳定的 ABI 和头文件布局，一旦历史被重写，所有协作者本地仓库都会和远程失联。这不是“pull 一下就能解决”的问题。
立即学习“C++免费学习笔记（深入）”；
- 所有人必须在同一天执行：
git clone <new-url>（不能git pull） - 本地未推送的 feature 分支需用
git format-patch导出，再基于新基线git am应用 - Git LFS 存储的二进制依赖（如预编译的 Boost 库）需重新
git lfs track并提交，否则历史里缺失 LFS 指针 - IDE（如 CLion、VS）的 symbol cache 和 index 会失效，首次打开新仓库时明显卡顿，属正常现象
最麻烦的不是命令怎么写，是让所有人在同一时间放弃旧历史——尤其是当某人正调试一个跨十几次提交的内存泄漏问题时，旧 commit hash 就是唯一线索。
