OXYGENHUB

Spec 0.6c: Git import semantics (union base, trailers, submodules, closure versus snapshot) 315167f3e208

Author
Andy McCall @andymccall <[email protected]>
When
· 2026-09-26 21:00 UTC
Signature
✔ signed by Andy McCall
Hash
315167f3e208a943e7502f4983c5b1beae826014e59b2857febe4ffb38c1e3f9
Depends on
f77698833f9f ff0af1ee299d
Depended on by
6e723b81f5b9 cfb7d414eae6
In bookmarks
agents-in-readme bare-hashes carried-not-removed carry-identical doctor-trust identical-sides keyless-tags main merge-remote-bookmark only-help-103 paths-for-resolutions-and-amend push-notes show-stat subrepo-pin-state switch-says
In tags
v0.1.0 v0.10.0 v0.11.0 v0.2.0 v0.3.0 v0.3.1 v0.4.0 v0.4.1 v0.4.2 v0.4.3 v0.4.4 v0.4.5 v0.4.6 v0.5.0 v0.5.1 v0.6.0 v0.7.0 v0.8.0 v0.9.0
Edits
4 atoms, 0 tree operations, 1 file

Browse the tree at this change

modified docs/spec.md +5 −3
…
1 unchanged lines
2 2
3 3
| | |
4 4
|---|---|
5 -
| **Status** | Draft 0.6b |
5 +
| **Status** | Draft 0.6c |
6 6
| **Format version** | 1 |
7 7
| **Date** | 2026-09-26 |
8 8
| **Audience** | Implementers, security reviewers, and contributors |
…
759 unchanged lines
768 768
769 769
`oxy git import <repo>` and `oxy git export <repo>` provide a lossless-enough bridge; `oxy git fetch/push` operate against a Git remote directly.
770 770
771 -
- **Import.** Each Git commit becomes one change whose edits are the diff against its first parent; merge commits become a change whose edits are the diff against the merged graph state. Atom identities are assigned by first appearance and cached in `.oxy/git/` so re-import is stable. Renames are detected heuristically (Git similarity ≥ 50%) on import only, then tracked exactly. The Git commit's `Change-Id` trailer, if present and 128 bits, becomes the ChangeId; otherwise one is derived as BLAKE3-128 of the Git commit hash, so re-import is idempotent.
771 +
- **Import.** Each Git commit becomes one change whose edits are the diff between the union of its parents' states and its tree, so a merge commit becomes a resolution exactly when the parents conflict in the change model, and an ordinary change otherwise. The commit's author and hash are recorded as `Git-Author` and `Git-Commit` trailers; the author key is the zero KeyId, since nobody can sign on the original author's behalf. Submodule entries are skipped. Renames are detected heuristically (Git similarity ≥ 50%) on import only, then tracked exactly; an implementation MAY import renames as delete-and-add until it does. The Git commit's `Change-Id` trailer, if present and 128 bits, becomes the ChangeId; otherwise one is derived as BLAKE3-128 of the Git commit hash, so re-import is idempotent. Note that a change's own closure is what it depends on, not the Git snapshot: the imported bookmark's state equals the Git tree, but checking out an individual imported change yields only the files it and its dependencies touch.
772 772
- **Export.** Each state along a bookmark becomes a Git commit whose tree is the materialized state. The ChangeId is written as a `Change-Id:` trailer and the ChangeHash as `Oxy-Hash:`. Conflicted states are exported with §9.5 markers and an `Oxy-Conflicted: true` trailer. Signatures are not exported; Git commits MAY be additionally signed with the Ed25519 key via SSH signature format.
773 773
- **Round trip.** Import followed by export MUST reproduce every tree hash. Export followed by import MUST reproduce every ChangeId.
774 774
…
59 unchanged lines
834 834
835 835
---
836 836
837 -
*Changelog.* Draft 0.6b (2026-09-26): §8.4 allows refusing a rewrite whose orphaned references have no specified conflict shape, defines removal, and notes the signature consequence.
837 +
*Changelog.* Draft 0.6c (2026-09-26): §23 import defines the base as the union of parent states, records author and commit trailers, skips submodules, and states the closure-versus-snapshot difference.
838 +
839 +
Draft 0.6b (2026-09-26): §8.4 allows refusing a rewrite whose orphaned references have no specified conflict shape, defines removal, and notes the signature consequence.
838 840
839 841
Draft 0.6a (2026-09-26): §13.4 fixes the pack and index file formats.
840 842
…
17 unchanged lines