mirror of
https://github.com/stablyai/orca.git
synced 2026-09-22 16:02:32 +00:00
6e2a4a824d
* fix(worktrees): stop surfacing prunable git worktrees as live workspaces A worktree still registered in git but whose directory was deleted (git's `prunable` state) was enumerated as a normal workspace, producing repeated pty:spawn DaemonProtocolError / fs:readDir ENOENT loops and a blank pane. - Parse the `prunable` porcelain field (Git >= 2.36) in both the main and relay worktree-list parsers. - For Git < 2.36 (no `prunable` field), probe each linked worktree path for existence on the fallback line-block path, skipping locked registrations to mirror git's own prunable rules. - Omit prunable worktrees from the detected-workspace enumeration only; removal/cleanup flows keep seeing them. - Extend the real-binary compatibility contract with the 2.36 `prunable` boundary. Fixes #8389 Claude-Session: https://claude.ai/code/session_018Rg1Bpq4GGwmz613hq6RSD * fix(worktrees): pin the prunable/locked porcelain annotations to their real Git 2.31 boundary The prunable and locked annotations landed in Git 2.31, five releases before `worktree list -z` (2.36); only -z defines the capability fallback boundary. Correct the compatibility contract so a future matrix entry in the 2.31-2.35 range passes, and reword the fallback comments: on 2.31-2.35 the annotations still parse and the existence probe is a backstop; only Git <2.31 relies on it outright. * fix(worktrees): omit prunable registrations from the Space scan A prunable registration has no directory to size or reclaim, so Space rendered it as a dead "Missing" row whose checkbox stayed disabled with no prune/remove affordance (reported on macOS after a reboot cleared /private/tmp under 16 registrations). Skip prunable entries in the scan, matching the workspace enumeration; removal flows list worktrees separately and still see them. --------- Co-authored-by: kaynan <kaynan.camargo@terceiro-sky.com.br> Co-authored-by: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
63 lines
3.8 KiB
Markdown
63 lines
3.8 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 with `prunable` marks | Line-block parser for Git before `worktree list -z` (2.36); the `prunable`/`locked` annotations still parse on Git 2.31–2.35, and a path-existence probe restores `prunable` detection for Git before 2.31 |
|
||
| `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.
|
||
|
||
## CI Contract
|
||
|
||
PR checks run the capability contract against real Git 2.25.5, 2.38.1, and
|
||
2.49.1 binaries. This spans the core-workflow baseline, the transitional
|
||
`merge-tree --write-tree` behavior before `--merge-base`, and current Git.
|
||
|
||
Keep the unit tests alongside that matrix. They cover concurrent probes,
|
||
native/WSL/SSH/relay isolation, and error-stream shapes that a single real
|
||
binary invocation cannot exercise deterministically.
|