Android 项目历史提交远程仓库资源过大，如何清理历史提交中无用的大文件

android项目跟gitlab关联之后，前期未忽略release/、debug/、build/ 目录中的文件，后期加上忽略配置之后，历史提交中还是存在大量release/、debug/、build/ 文件，项目的分支也比较多，导致每次克隆都需要花费很长的时间。这里的操作是用于清理历史提交中的无用大文件，不会影响项目本身。

适用于 GitLab / GitHub / Azure DevOps 等任何标准 Git 仓库

操作会重写所有分支历史，推送后团队必须重新 clone，请提前备份并通知全员。

一、效果

从整条历史 里彻底抹掉 release/、debug/、build/ 及其所有子文件
仓库体积从 14 GB → 约 500-600 MB（实测 93 % 缩小）
保留其他文件（含有用 *.apk）不变

二、前置条件

1.Owner / Maintainer 权限

需要关闭 Protected branches 以允许强推

需要生成 Personal Access Token（用于 API 刷新统计）

2.安装 git-filter-repo

bash 复制代码

# Windows（Git Bash / PowerShell）
pip install --user git-filter-repo
# macOS
brew install git-filter-repo
# Linux
sudo apt install git-filter-repo

三、完整步骤

0. 备份（必须）

bash 复制代码

git clone --mirror <仓库地址>  backup.git
# 或创建 bundle
git bundle create backup.bundle --all

1. 拉取最新代码

bash 复制代码

git clone <仓库地址>  android-project
cd android-project
git fetch origin --prune

2. 一键剔除三个目录

bash 复制代码

git filter-repo \
  --path build/ \
  --path release/ \
  --path debug/ \
  --invert-paths \
  --force

耗时：几十秒 ~ 几分钟（看体积）
输出：New history written... Completely finished after xx seconds

3. 清理垃圾 & 瘦身

bash 复制代码

rm -f .git/objects/pack/tmp_pack_*   # Windows 若被占用可跳过
git reflog expire --expire=now --all
git gc --prune=now --aggressive      # 再被占用按 y/n 时选 n

检查大小：

bash 复制代码

git count-objects -vH
# size-pack 应 ≈ 500-600 MiB

4. 重新添加远程（filter-repo 会删掉 origin）

bash 复制代码

git remote add origin <仓库地址>

5. 关闭 Protected branches

GitLab → Settings → Repository → Protected branches → Unprotect 所有相关分支（至少 master）。

6. 强制推送新历史

bash 复制代码

git push origin --force --all
git push origin --force --tags

成功标志：无 pre-receive hook declined
传输量 ≈ 上一步 size-pack 数值

7. 恢复保护 & 刷新网页统计

重新把 master 等分支设为 Protected
调用 API 立即刷新磁盘用量：

bash 复制代码

curl --request PUT \
  --header "PRIVATE-TOKEN: <你的Token>" \
  --data "description=trigger disk usage recalc" \
  http://<gitlab>/api/v4/projects/<项目ID>

1-2 分钟后网页 → Repository → Storage 将显示 ≈ 1 GiB（原 14 GiB）

四、验证

bash 复制代码

# 1. 历史里再无目标目录
git log --all --name-only | grep -E '(^|/)build/' | wc -l   # → 0

# 2. 克隆体积
git clone --depth 1 <仓库地址>  test
du -sh test                                                  # → ~150 MiB
rm -rf test

五、团队协同

1.所有人重新 clone：

bash 复制代码

git clone <仓库地址>

旧本地库无法 pull，克隆成功之后直接删除即可。

2.把以下目录写进 .gitignore 防止再次提交：

bash 复制代码

build/
release/
debug/
app/build/
app/release/
app/debug/

3.CI 产物改走 Artifact 或 Package Registry，不再进 Git 历史。

六、常见问题

现象	原因	解决
`pre-receive hook declined`	分支受保护	先 Unprotect，推送后再恢复保护
`bad object` / 推送断开	本地仍是旧历史	重新 clone 或用 `reset --hard origin/分支`
网页大小未变	缓存未刷新	用 API 触发重算或等待 30 min
`Unlink of file ... failed`	Windows 句柄占用	按 `n` 跳过即可，数据已写完

七、一句话总结

备份 → filter-repo 剔除三目录 → 强制推送 → 通知全员重新 clone → 网页刷新完成！

操作一次即可永久瘦身，后续只加 .gitignore 不再进大文件。