git filter-repo 必须加 --force 是因为它默认拒绝在非全新克隆的仓库（含 reflog、shallow 状态或未推送提交）上运行，报错“ERROR: This repository is not a fresh clone”，加 --force 表示用户已备份并明确承担风险；--path 与 --strip-blobs-bigger-than 不可混用，二者逻辑不同、仅前者生效；重写历史后 origin 被清空是防误推的设计，需手动重新添加；瘦身完成后必须执行 git gc --aggressive --prune=now 才能彻底释放空间。
git filter-repo 为什么必须用 --force
因为 git-filter-repo 默认拒绝在非全新克隆的仓库上运行，它会检查 .git/shallow、引用日志、未推送的提交等状态。一旦你本地仓库有过 push 或 rebase 操作，它就认为“不干净”，直接报错退出：ERROR: This repository is not a fresh clone。
加 --force 是绕过这个安全检查的唯一方式——但前提是：你已备份好当前工作区和 .git 目录。这不是“跳过警告”，而是明确告诉工具：“我清楚后果，且已做好回滚准备”。没备份就加 --force，等于主动放弃历史恢复能力。
删大文件时 --path 和 --strip-blobs-bigger-than 别混用
--path 是路径级精准剔除，--strip-blobs-bigger-than 是大小阈值扫描剔除，二者逻辑不同、触发时机也不同。混用会导致行为不可预测，比如：
-
git filter-repo --path docs/ --strip-blobs-bigger-than 50M实际只生效第一个参数（--path），后者被忽略 - 想同时删某目录 + 所有超限文件？得拆成两次独立执行，且第二次要基于第一次的结果仓库再跑
-
--strip-blobs-bigger-than不区分文件类型，PDF、ZIP、编译产物一视同仁；而--path可以精准命中build/或dist/这类典型垃圾目录
分支重命名后 origin 被自动清空是设计使然
git-filter-repo 重写历史后，所有 commit hash 全部变更，原有远程引用彻底失效。它主动删除 origin 配置，不是 bug，是防止你误推旧历史覆盖远程仓库。
重新绑定前必须手动执行：
-
git remote add origin <new-url>（不能用set-url，因为 origin 已不存在） -
git push --all origin推送所有本地分支 -
git push --tags origin单独推 tags（--all不含 tags）
漏掉 --tags，tag 就永远丢了——这点容易被忽略，尤其当项目依赖 tag 做版本发布时。
瘦身之后别忘了 git gc --aggressive
git-filter-repo 只改写对象数据库，不自动压缩或清理冗余松散对象。执行完后立即运行：
git gc --aggressive --prune=now
其中 --prune=now 强制清理所有未被引用的对象（包括 reflog 中已过期的），--aggressive 启用更耗时但压缩率更高的打包策略。不执行这步，仓库体积可能只缩小 30%～50%，而非宣称的 80%+。
顺带一提：git count-objects -v 的 size-pack 字段才是真实体积，别只看 du -sh .git ——后者包含临时 unpacked 对象，不准。
