Git仓库维护者如何在不影响推拉带宽的前提下清理历史并保留单提交

核心思路 #

要在保留当前工作目录内容的前提下彻底清理历史，同时避免推送1GB大提交、用户重复拉取已有文件，关键是复用仓库中已存在的大文件对象，让新的唯一提交直接引用这些对象，而非重新生成。

维护者操作步骤 #

1. 创建当前状态的快照提交 #

确保工作目录干净且内容是最终需要保留的状态，创建新提交：

git add .
git commit -m "清理历史后的唯一提交"

这一步仅生成包含当前所有文件的提交，仓库体积暂未变化。

2. 替换原根提交，复用已有对象 #

通过git replace让新提交成为根提交，同时复用原根提交中的大文件对象：

# 获取原根提交的哈希值
ROOT_COMMIT=$(git rev-list --max-parents=0 HEAD)
# 获取刚创建的新提交哈希
NEW_COMMIT=$(git rev-parse HEAD)
# 替换原根提交，使新提交成为新的根（无父提交）
git replace $ROOT_COMMIT $NEW_COMMIT^

3. 重写历史并压缩仓库 #

使用git filter-repo（推荐替代git filter-branch，更高效稳定）彻底移除旧历史：

git filter-repo --force

执行后仓库仅保留新创建的唯一提交，且大文件对象复用原有内容，仓库体积会降至约960MB（950MB基础文件+10MB修改文件）。

4. 强制推送新历史到远程 #

推送时强制覆盖远程分支，但由于大文件对象已存在于远程仓库，实际仅推送新提交的元数据和10MB修改内容：

git push origin main --force

用户端同步步骤 #

用户本地已存在950MB文件，同步时无需重新下载：

• 可选：先备份本地仓库，避免数据丢失
• 拉取远程新历史并重置本地分支：

git fetch origin
git reset --hard origin/main

Git会自动识别本地已有的大文件对象与远程新提交中的对象哈希一致，仅拉取必要的元数据和10MB修改内容。

效果验证 #

• 维护者端：执行du -sh .git查看仓库体积，应显示约960MB，而非原10GB
• 用户端：拉取后本地仓库体积无大幅增长，工作目录内容与之前一致
• 远程仓库：体积大幅缩减，仅保留唯一提交及必要对象

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