Git 分支重写时逐提交执行 go fmt 的自动化方案

本文介绍如何使用 git filter-branch（或更现代的 git filter-repo）安全、自动地对分支中每个提交依次运行 go fmt，实现代码格式化与历史重写一体化，避免手动 cherry-pick 带来的冲突、误提交和元数据污染问题。

在 Go 项目协作中，常需将旧分支（如 feature/X）整体应用统一代码风格——尤其是补全缺失的 go fmt 格式化。若手动逐提交 cherry-pick + amend，极易引发文件误提交（如 git commit -a 意外纳入未修改文件）、时间戳混乱、格式化干扰 patch 应用等问题，维护成本高且不可靠。

推荐采用 Git 历史重写（history rewriting）方案，核心是 对每个提交的暂存区内容执行 go fmt，再生成新提交。传统上可使用 git filter-branch：

# 确保在目标分支（如 X）上操作，并已备份
git checkout X

# 使用 --tree-filter 对每个提交的工作树执行 go fmt（作用于所有 .go 文件）
git filter-branch --tree-filter 'find . -name "*.go" -exec go fmt {} + 2>/dev/null || true' \
  --prune-empty \
  --force \
  HEAD

⚠️ 注意事项：

• --tree-filter 会在每个提交检出完整工作树后执行命令，较慢但语义清晰；若追求性能，可用 --index-filter（需配合 git ls-files 和 git update-index，复杂度较高）；
• 2>/dev/null || true 避免因无 .go 文件导致命令失败中断流程；
• --prune-empty 自动跳过格式化后无变更的空提交；
• --force 是必需参数（防止意外覆盖）；
• 执行后所有提交 SHA-1 将变更，必须强制推送：git push --force-with-lease origin X；
• 务必提前通知团队成员：他们需执行 git fetch && git reset --hard origin/X 以同步新历史，否则会引入重复/分裂提交。

✅ 更优替代：推荐使用现代工具 git filter-repo（Git 官方推荐替代 filter-branch）：

# 安装后（pip3 install git-filter-repo），在干净克隆中操作更安全
git clone --no-hardlinks --shared . /tmp/x-formatted
cd /tmp/x-formatted
git filter-repo --mailmap <(echo "# auto-format via go fmt") \
  --tree-filter 'find . -name "*.go" -exec go fmt {} + 2>/dev/null || true' \
  --refs X

git filter-repo 更快、更安全、默认保留原始作者/提交时间（可通过 --mailmap 或 --preserve-commit-hashes 进一步控制），且不污染 reflog。

最后验证效果：

# 比较格式化前后差异（仅显示 go 文件变更）
git diff master...X -- "*.go"

# 检查各提交是否均已格式化（无 go fmt 差异）
git rebase -i --exec 'go fmt ./...' X~10  # 快速抽检最近10个提交

总结：避免手工 cherry-pick 循环，应优先选用 git filter-repo（首选）或 git filter-branch（兼容旧环境）进行声明式历史重写。它确保每步 go fmt 在纯净上下文中执行，保持提交原子性、作者信息完整性与团队协作安全性。