mirror of
https://github.com/stablyai/orca.git
synced 2026-10-17 08:03:14 +00:00
Neil
6f37ef1841
Old Git worktree, ref-search, and merge-tree fallbacks retried unsupported flags on recurring operations, flooding subprocess traces. Centralize capability probing per native, WSL, and SSH execution host, coalesce concurrent probes, and retry periodically for in-place Git upgrades.
60 lines
3.6 KiB
Markdown
60 lines
3.6 KiB
Markdown
# Git Compatibility Policy
|
|
|
|
## Scope
|
|
|
|
Orca executes the user's Git binary on three kinds of execution host: native,
|
|
WSL, and SSH. Each host can have a different Git version, so compatibility
|
|
state must be scoped to the host that actually runs the command.
|
|
|
|
Git 2.25 is the core-workflow compatibility baseline for command selection. It
|
|
is the oldest line that covers Orca's baseline use of porcelain v2, `branch
|
|
--show-current`, `restore`, and sparse checkout. Optional features that need a
|
|
newer Git must degrade safely and cache the missing capability. Orca does not
|
|
currently block older Git at startup, but new command construction should not
|
|
assume features introduced after this baseline.
|
|
|
|
## Capability Rules
|
|
|
|
When a newer Git feature materially improves correctness or performance:
|
|
|
|
1. Keep a baseline-compatible command or parser as the fallback.
|
|
2. Detect rejection with a narrow predicate for that option or subcommand.
|
|
3. Run the preferred command through `GitCapabilityCache` so a rejection is
|
|
remembered for the native host, WSL distro, or SSH provider that produced it.
|
|
4. Retry after the cache interval so an in-place Git upgrade self-heals without
|
|
restarting Orca.
|
|
5. Test the first fallback, later calls that skip the rejected probe, concurrent
|
|
probe coalescing, and execution-host isolation where applicable.
|
|
|
|
Do not branch only on a parsed `git --version`. Vendor builds can backport
|
|
features, and wrappers can report a host version that differs from the binary
|
|
used inside WSL or SSH. A behavior probe plus a precise fallback is the final
|
|
authority.
|
|
|
|
## Current Capabilities
|
|
|
|
| Capability | Preferred behavior | Compatibility behavior |
|
|
| ----------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
| `worktree-list-z` | NUL-delimited worktree paths | Line-block parser for Git before `worktree list -z` |
|
|
| `rev-parse-path-format` | Absolute repo metadata paths | Resolve legacy relative output against the scanned repo |
|
|
| `for-each-ref-exclude` | Exclude remote HEAD before the output limit | Request extra refs, then filter remote HEAD in Orca |
|
|
| `merge-tree-write-tree` | Derive real-merge conflicts and no-op tree proofs | Omit the conflict summary and keep conservative branch cleanup behavior before Git 2.38 |
|
|
| `merge-tree-merge-base` | Supply the already-resolved merge base | Use the older two-commit `merge-tree --write-tree` form |
|
|
|
|
## Why Not `simple-git`
|
|
|
|
`simple-git` is a process wrapper around the installed Git binary. Its custom
|
|
options and `raw` API pass arguments through to Git, so it cannot make a newer
|
|
flag work on an older binary or choose Orca's semantic fallback automatically.
|
|
It provides version reporting and subprocess queueing, but Orca already needs
|
|
its own WSL/SSH routing, cancellation, tracing, redaction, process cleanup, and
|
|
bounded output handling. Replacing the runner would move—not remove—the
|
|
capability problem.
|
|
|
|
## Reliability Follow-up
|
|
|
|
The strongest remaining gate is a small old-Git contract matrix that runs the
|
|
capability tests against Git 2.25, a pre-2.36 release, and current Git. Keep the
|
|
unit tests regardless: they cover localized error text, WSL/SSH isolation, and
|
|
concurrent probes that a single container run does not exercise.
|