OXYGENHUB

Docs: bookmarks in the guide, spec status table, plan fbda43e7d8ed

Author
Andy McCall @andymccall <[email protected]>
When
· 2026-09-27 14:05 UTC
Signature
✔ signed by Andy McCall
Hash
fbda43e7d8ed12af62a8f5d9a91be456da9a6ace2f74455600d838741dc78f47
Depends on
50a046e439e9 86fe29fd62ea 96f7610fa666 ee06a6c557b7 ff0af1ee299d
Depended on by
4afab467e35f bf3a67819b59 4fe7d6045860 314db9b4f3f8 4dee277c327a
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, 3 files

Browse the tree at this change

modified docs/guide.md +22 −0
…
72 unchanged lines
73 73
rewrites, and a content hash (`#7469d16c…`) that changes when the change is
74 74
edited. Use whichever you have; prefixes work.
75 75
76 +
## 3a. Bookmarks: branches without merges
77 +
78 +
A bookmark names a state; each workspace works on one (`main` to begin
79 +
with). Because changes commute, "merging" is the union of two bookmarks'
80 +
heads, with no merge change and any real conflict recorded as in section 6.
81 +
82 +
```
83 +
oxy bookmark create feature        # at the working copy's base
84 +
oxy bookmark switch feature        # check it out; commits now go here
85 +
oxy commit -m "Feature work"
86 +
oxy bookmark switch main
87 +
oxy merge feature                  # main now holds both; working copy follows if clean
88 +
oxy bookmark list                  # ● current, heads, ↑n/↓n against origin
89 +
oxy push -b feature                # publish a bookmark other than the current one
90 +
oxy bookmark set feature 658990aa  # move it; oxy bookmark delete feature to drop it
91 +
```
92 +
93 +
`oxy checkout feature` materialises a bookmark without switching to it, and
94 +
a bookmark name works wherever a change is expected when it has one head.
95 +
Each workspace remembers its own bookmark, so two directories can sit on
96 +
two bookmarks of one repository.
97 +
76 98
## 4. Fix up history
77 99
78 100
Oxygen keeps its own record of every operation, so all of these are safe to
…
265 unchanged lines
modified docs/plan.md +1 −1
…
39 unchanged lines
40 40
41 41
Rules as above. Spec Draft 0.8 defines each item; implement in this order, each with tests, a gate, and an oxy commit.
42 42
43 -
- [ ] Multiple bookmarks (spec §10.1): `oxy bookmark create|set|delete|list|switch`, per-workspace current bookmark, `oxy merge BOOKMARK`, `oxy checkout NAME`, bookmark names resolved before change prefixes; push/pull/log act on the current bookmark; `oxy push -b`.
43 +
- [x] Multiple bookmarks (spec §10.1): `oxy bookmark create|set|delete|list|switch`, per-workspace current bookmark, `oxy merge BOOKMARK`, `oxy checkout NAME`, bookmark names resolved before change prefixes; push/pull/log act on the current bookmark; `oxy push -b`.
44 44
- [ ] Subrepositories (spec §7.8, §23): node kind `subrepo`, pin encoding, `.oxymodules`, snapshot stops at nested repositories and reads their pin, checkout moves or leaves nested repositories, `oxy submodule add|update|status|remove`; Git import/export of gitlinks and `.gitmodules` (test with a mirror of tetriblox, never the live repository).
45 45
- [ ] Partial commits (spec §12.3): `oxy commit PATH..` and `oxy commit --interactive` (hunk = one edit or tree operation, dependent hunks pulled in), sharing the split machinery.
46 46
- [ ] Blame (spec §27): `oxy blame PATH [--json]` from atom keys, with author and date; renames followed.
…
26 unchanged lines
modified docs/spec.md +1 −0
…
878 unchanged lines
879 879
| Objects, hashing, deterministic CBOR (§5) | Implemented; format 2 repositories, migration from format 1 |
880 880
| Change graph, commutation, conflicts and resolution (§6–§9) | Implemented, including order, delete/insert, tree, replace, and mode conflicts; workspace conflicts (§9.7) and exit status 3 are not detected |
881 881
| Rewrites (§8.4) | Implemented: describe, amend (also into older changes), split, abandon; orphaned references re-anchored |
882 +
| Bookmarks, per-workspace current bookmark, merge by union (§10.1) | Implemented |
882 883
| Operation log, undo (§12.1) | Implemented; `redo` reserved |
883 884
| Snapshots and the stat cache (§12.3, §12.4) | Implemented; no file-system monitor yet |
884 885
| Storage: loose objects, packs, GC, checkpoints, batching (§11, §13, §21) | Implemented; pack indexes are read fully rather than mapped |
…
84 unchanged lines