Git 兼容性策略¶
范围¶
Orca 会在三种执行主机上运行用户的 Git 二进制：原生、WSL 和 SSH。每种主机都可能具有不同的 Git 版本，因此兼容性状态必须限定在实际运行命令的主机范围内。
Git 2.25 是命令选择的核心工作流兼容性基线。它是覆盖 Orca 对 porcelain v2、branch --show-current、restore 和稀疏检出的基线使用的最旧版本线。需要更新 Git 的可选功能必须安全降级，并缓存缺失的能力。Orca 当前不会在启动时阻止旧版 Git，但新的命令构造不应假设该基线之后引入的功能。
能力规则¶
当较新的 Git 功能能实质性提升正确性或性能时：
- 保留一个与基线兼容的命令或解析器作为回退。
- 针对该选项或子命令，使用狭窄谓词检测拒绝。
- 通过
GitCapabilityCache运行首选命令，以便记住产生该拒绝的原生主机、WSL 发行版或 SSH 提供程序。 - 在缓存间隔后重试，以便就地升级 Git 后无需重启 Orca 即可自愈。
- 测试首次回退、后续跳过被拒绝探测的调用、并发探测合并，以及适用时的执行主机隔离。
不要仅根据解析的 git --version 进行分支判断。厂商构建可能回移功能，包装器也可能报告与 WSL 或 SSH 内部实际使用的二进制不同的主机版本。行为探测加上精确回退才是最终依据。
当前能力¶
| 能力 | 首选行为 | 兼容行为 |
|---|---|---|
fetch-no-write-fetch-head |
获取私有 rebase 引用，而不更改工作树本地的 FETCH_HEAD |
在 Git 2.29 之前，按工作树 Git 目录串行化所有 Orca fetch/pull 操作 |
worktree-list-z |
使用 NUL 分隔的工作树路径，并带有 prunable 标记 |
针对早于 worktree list -z（2.36）的 Git 使用行块解析器；prunable/locked 注释在 Git 2.31–2.35 上仍可解析，并且路径存在性探测可恢复 Git 2.31 之前对 prunable 的检测 |
rev-parse-path-format |
绝对仓库元数据路径 | 相对于被扫描的仓库解析旧版相对输出 |
for-each-ref-exclude |
在输出限制之前排除远程 HEAD | 请求额外引用，然后在 Orca 中过滤远程 HEAD |
merge-tree-write-tree |
推导真实合并冲突和空操作树证明 | 在 Git 2.38 之前省略冲突摘要，并保持保守的分支清理行为 |
merge-tree-merge-base |
提供已解析的合并基 | 使用旧的两提交 merge-tree --write-tree 形式 |
失败开放的占位符¶
GitCapabilityCache 记录 Git 拒绝 的命令。Git 不认识的 git log --format 占位符不会被拒绝：Git 会原样回显它并以零退出，因此没有可记住的错误，也没有可缓存的探测。在一条记录中同时请求两种形式，并在解析时选择。
| 占位符 | 首选行为 | 兼容行为 |
|---|---|---|
%(decorate:…) |
Git 2.43 使用 \x1f 分隔提交装饰，因此包含逗号的引用名称可以保留 |
同一条记录还携带 %D（Git 2.10）；未展开的 %(decorate 占位符会选择它，代价是按逗号拆分 |
为什么不用 simple-git¶
simple-git 是围绕已安装 Git 二进制的进程包装器。它的自定义选项和 raw API 会将参数透传给 Git，因此它无法让较新的标志在旧二进制上生效，也无法自动选择 Orca 的语义回退。它提供版本报告和子进程排队，但 Orca 已经需要自己的 WSL/SSH 路由、取消、跟踪、脱敏、进程清理和有界输出处理。替换运行器只会转移——而不是消除——能力问题。
CI 契约¶
PR 检查会针对真实的 Git 2.25.5、2.38.1 和 2.49.1 二进制运行能力契约。这涵盖了 2.29 之前串行化 FETCH_HEAD 的回退、--merge-base 之前过渡性的 merge-tree --write-tree 行为，以及当前 Git。
三条通道并行运行，容器通道中的每次 Git 调用都会产生一次容器启动开销，因此它们的实际耗时取决于运行器争用，而不是 Git。在通道开始前构建 2.25.5 二进制并拉取镜像：任何与它们同时运行的重型任务都会计入正在执行的某个边界用例，并表现为 Vitest 超时，而不是缓慢的设置步骤。
保留该矩阵旁边的单元测试。它们覆盖并发探测、native/WSL/SSH/relay 隔离，以及单次真实二进制调用无法确定性地验证的错误流形态。
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 orca48/orca