Git 2.56 迁移时的脚本兼容检查清单

Git 2.56 迁移时，最容易漏掉的不是“命令找不到”，而是脚本仍然能运行，却因为输出文案、帮助参数退出码或图形化历史展示变化而做出错误判断。稳妥的检查方式是先固定旧版基线，再把脚本依赖拆成命令入口、标准输出、标准错误和退出码四类，最后用隔离仓库回归后再灰度切换。

官方地址：https://git-scm.com/

Git 2.56 的官方发布说明：https://github.com/git/git/blob/master/Documentation/RelNotes/2.56.0.adoc

把 Git 的人类可读提示当成“可能变化的显示层”，把明确格式、字段和退出码当成脚本接口。迁移的验收标准不是版本号变了，而是同一批输入仍得到同一类业务结论。

先固定旧版基线，别急着替换 runner

先选一台仍运行旧版 Git 的 CI runner，收集脚本实际调用的命令和三类结果：成功时的 stdout、失败时的 stderr、进程退出码。还要记录仓库形态，例如普通工作树、浅克隆、裸仓库和多 worktree，因为同一命令在这些状态下可能走不同分支。

基线记录不需要保存整段日志，保存脚本真正消费的字段即可。比如脚本只判断分支名，就记录分支名；如果脚本把 git log --graph 的每一行拆成节点，就要把这段解析标为高风险，而不是只记录最终数量。

# 迁移前固定 Git 版本与脚本的三类接口结果
set -eu

# 版本信息用于区分基线，不要拿整段人类提示作为业务判断
git --version

# 示例命令只输出稳定的引用字段，便于和新版本做差异对照
git for-each-ref --format='%(refname:short) %(objectname)' refs/heads

# 显式保存失败状态，避免把 stderr 文案误当成退出码
if git rev-parse --verify HEAD >git.stdout 2>git.stderr; then
  echo "git_exit=0"
else
  code=$?
  echo "git_exit=$code"
fi

逐项检查 Git 2.56 的脚本敏感面

Git 2.56 增加了 git refs 的 create、delete、update 和 rename 子命令。新命令方便脚本使用底层引用操作，但迁移时要确认旧 runner 是否仍需兼容：如果脚本只是更新分支引用，不要因为新命令存在就立即替换已有的 git update-ref；先定义成功、旧值不匹配和引用不存在时各自的处理。

另一个容易被忽略的变化是，大多数 Git 子命令直接请求 -h 或 --help 时，退出码从 129 调整为 0。若探测脚本通过“帮助命令必须非零”来判断参数是否被接受，Git 2.56 会改变这个判断。正确做法是把帮助探测和业务命令分开，不要用一个通用的非零断言覆盖两者。

此外，git log --graph 对视觉根提交的缩进表现发生变化，git log --follow 对非线性历史的跟踪更可靠，git repo info 也增加了绝对和相对路径相关的输出能力。这些改动未必是破坏性变更，但都提醒我们：脚本不应按空格位置、图形字符或自然语言提示解析结果。

迁移清单可以按下面四项逐条打勾：

把文本解析改成稳定格式

兼容改造的核心不是把所有脚本重写，而是先找到“显示层泄漏到业务层”的地方。分支、标签和对象清单优先使用 --format；状态类命令优先使用文档明确的机器可读选项；输出中只需要一个字段时，就让 Git 只返回一个字段。对 stderr，除非脚本确实要展示诊断，否则把它和业务结果分离。

# 用字段格式读取引用，不依赖 git branch 的对齐空格和标记
set -eu

git for-each-ref \
  --format='%(refname:short)%09%(objectname)' \
  refs/heads | while IFS=$(printf '\\t') read -r branch commit; do
  # 分隔符固定为制表符，业务逻辑只消费两个字段
  [ -n "$branch" ] || continue
  printf 'branch=%s commit=%s\\n' "$branch" "$commit"
done

# 帮助探测单独处理：0 代表帮助已输出，不代表业务动作成功
if git refs --help >/tmp/git-refs-help 2>/tmp/git-refs-help.err; then
  echo "help_available=true"
else
  code=$?
  echo "help_available=false exit=$code"
fi

如果脚本必须兼容旧版 Git，可以在入口处做一次能力探测，然后选择已验证的实现路径。探测只回答“命令是否存在”，不要顺便执行会修改引用的动作；引用更新仍要使用旧值保护或等价的并发控制，防止迁移期间把竞态误判成版本问题。

在隔离仓库执行迁移回归

回归仓库应包含能触发脚本分支的最小样本，而不是直接拿生产仓库试跑。至少准备一条普通分支、一条空结果路径、一个无效参数、包含根提交或非线性历史的提交图，以及两个 worktree。每个样本都记录脚本的业务断言：应该输出什么、应该拒绝什么、应该返回哪个退出码。

重点关注四类误报：一是新版本提示更友好，但脚本把 stderr 非空当失败；二是视觉输出变化，但脚本仍按列位置切分；三是帮助探测从非零变为零，脚本把能力探测判反；四是新命令可用，但旧 runner 仍在混合执行，导致结果依赖机器版本。

# 用同一组样本分别跑旧版与 Git 2.56，比较业务结论而非整段日志
set -eu

cases="normal empty invalid-arg non-linear-history multi-worktree"
for case in $cases; do
  # 每个样本都应由脚本返回明确的业务状态，失败也要保留日志
  ./check-git-script.sh "fixtures/$case" \
    >"out-$case.txt" 2>"err-$case.txt" || code=$?
  code=${code:-0}
  printf '%s exit=%s\\n' "$case" "$code"
  unset code
done

灰度切换、回滚和最终验收

通过隔离回归后，先只切换一台非关键 runner，并观察脚本的成功率、异常退出码和人工复核样本。不要只看 CI 绿灯：如果脚本的产物是分支清理清单、发布引用或路径列表，还要抽样确认产物字段没有错位。

建议把验收条件写成三句话：同一输入的业务结论不变；预期的新命令在声明的最低版本上可用；任何失败都能保存 stdout、stderr、退出码和 Git 版本。若任一条不满足，先把 runner 切回旧版 Git，再修复解析或能力探测，不要在生产引用上反复试错。

Git 2.56 迁移速查：先记基线，再查 git refs 与 -h 退出码；再消除对 git log --graph、提示文案和空格对齐的依赖；最后用普通仓库、空结果、错误输入、非线性历史和多 worktree 做灰度回归。

常见问题

Git 2.56 一定会让旧脚本失效吗？不一定。多数风险来自脚本把人类可读输出当成稳定接口，而不是所有命令都发生了不兼容变化。

已经使用 git update-ref，还需要改成 git refs 吗？不需要为了追新命令而改。先确认新命令的最低版本、错误处理和并发保护，再决定是否迁移。

为什么不能只比较命令输出文件？因为提示文案、图形化日志和路径展示可能变化；应比较脚本消费的字段、业务结论和退出码。