用 git blame --ignore-rev 跳过格式化提交的实战配置

问题场景

团队引入统一格式化工具后，一次提交可能改动数百行，例如把两空格缩进改成四空格、调整引号或换行。功能没有变化，但 git blame 会把每一行都指向这次格式化提交。之后查看某个函数是谁写的、为什么这样写时，历史被格式化提交“截断”。重写历史成本高且有风险，更合适的做法是让 git blame 在显示时跳过这些纯格式化提交。

Git 提供了 git blame --ignore-rev <提交>，也支持把要忽略的提交写入文件，再通过配置 blame.ignoreRevsFile 让仓库默认使用。它只改变 blame 的归属计算，不删除提交，也不改变 git log 和 git diff 的结果。

收集纯格式化提交

先确认提交确实只做格式化。可以在仓库中查看提交统计和忽略空白后的差异：

git show --stat <格式化提交哈希>
git diff -w <格式化提交哈希>^ <格式化提交哈希> -- <文件路径>

如果 git diff -w 没有输出，通常说明只有空白变化；如果还有引号、分号等格式变化，需要人工判断是否应忽略。把确认过的完整提交哈希收集起来，不要使用短哈希。

创建忽略文件并配置

在仓库根目录创建 .git-blame-ignore-revs，每行写一个完整哈希，空行和以 # 开头的注释行可帮助维护：

# 2024-01 统一格式化 app.txt
1111111111111111111111111111111111111111
2222222222222222222222222222222222222222

然后在当前仓库配置：

git config blame.ignoreRevsFile .git-blame-ignore-revs
git config --get blame.ignoreRevsFile

配置是仓库本地的，不会自动随克隆同步；团队应把忽略文件和配置命令写进项目说明。临时查看也可以不配置，直接使用：

git blame --ignore-revs-file .git-blame-ignore-revs -- <文件路径>

可运行的最小示例

下面脚本在临时目录创建仓库，模拟一次纯格式化提交，写入忽略文件并验证 blame。示例哈希由脚本动态生成，不需要手工替换。

#!/usr/bin/env bash
set -eu
workdir="$(mktemp -d)"
cd "$workdir"
git init -q
git config user.name 'demo'
git config user.email 'demo@example.com'

cat > app.txt <<'EOF'
function greet(name) {
  return 'hello, ' + name;
}
EOF
git add app.txt
git commit -qm 'feat: add greet'

# 模拟纯格式化：只改缩进
cat > app.txt <<'EOF'
function greet(name) {
    return 'hello, ' + name;
}
EOF
git add app.txt
git commit -qm 'style: format app.txt'
fmt_rev="$(git rev-parse HEAD)"

printf '# 纯格式化提交\n%s\n' "$fmt_rev" > .git-blame-ignore-revs
git add .git-blame-ignore-revs
git commit -qm 'chore: add blame ignore revs'

git config blame.ignoreRevsFile .git-blame-ignore-revs
git blame app.txt
git blame --ignore-rev "$fmt_rev" app.txt

运行方法：

chmod +x demo.sh
./demo.sh

脚本输出中，忽略生效后，app.txt 的行应归到 feat: add greet，而不是 style: format app.txt。在真实仓库中，把哈希换成实际值，再用 git blame -L <起始行>,<结束行> -- <文件路径> 查看函数范围的历史。

边界与限制

--ignore-rev 只影响 blame 的显示归属，不会改变提交内容。被忽略的行会继续向前寻找最近一个未被忽略的提交；如果格式化提交里混入了语义修改，忽略后这些修改的归属会被隐藏，因此不要把混合提交加入忽略文件。

忽略文件中的哈希必须完整并存在于当前历史。执行 rebase、amend 或强制重写历史后，旧哈希可能失效，需要重新收集并更新文件。团队协作时，.git-blame-ignore-revs 可以提交到仓库，但 blame.ignoreRevsFile 配置需要每个成员在本地执行，或者统一使用 --ignore-revs-file 参数。

该能力需要当前 Git 版本支持，使用前可用 git blame -h 查看是否包含 --ignore-rev 和 --ignore-revs-file。不要将其用于合并提交或包含业务逻辑的提交；它适合经过审查的、纯格式化的批量改动。