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 |