| 1 |
# Oxygen |
| 2 |
|
| 3 |
Oxygen (`oxy`) is a distributed, commutative version control system written in Rust for large repositories. See [docs/spec.md](docs/spec.md) for the specification. |
| 4 |
|
| 5 |
It is self-hosting: this directory is an Oxygen repository, and the project's own history is kept with `oxy`, not with Git. |
| 6 |
|
| 7 |
## What is different |
| 8 |
|
| 9 |
- **History is a set of changes, not a chain of snapshots.** A change records what it did to identified lines and tree nodes and which earlier changes it depends on. Changes that do not depend on each other commute, so there are no merge commits and rebasing independent work rewrites nothing. |
| 10 |
- **Conflicts are data.** A conflicted state can be committed, pushed and pulled. Resolving one is an ordinary edit followed by a commit. |
| 11 |
- **Every change has a stable ID and a content hash.** The ID survives rewrites; the hash makes history tamper-evident. |
| 12 |
- **Everything is signed.** Composite Ed25519 + ML-DSA-65 signatures on changes and on every bookmark update, verified against a trust policy that lives in the repository. |
| 13 |
- **Every operation is undoable** through an operation log. |
| 14 |
- **Large files are chunked** with content-defined chunking into a BLAKE3-addressed store. |
| 15 |
|
| 16 |
## Builds |
| 17 |
|
| 18 |
Every push is built and tested by OxygenFlow. See the project's runs at [https://oxygenhub.io/andymccall/oxygen/flow](https://oxygenhub.io/andymccall/oxygen/flow). |
| 19 |
|
| 20 |
## Status |
| 21 |
|
| 22 |
Early, but usable for its own development. Implemented: the object model, the change graph with conflict detection and resolution, the working copy (`status`, `commit`, `checkout`, `diff`, `undo`), identities and signatures, remotes over local paths and HTTP(S) with `clone`, `fetch`, `pull`, `push`, the reference server `oxy serve`, the trust policy, and packed storage. |
| 23 |
|
| 24 |
Not yet: checkpoints for very long histories, history editing (`rebase`, `split`, `edit`), multiple workspaces, garbage collection with retention, and the Thin client profile for constrained machines. |
| 25 |
|
| 26 |
## Building |
| 27 |
|
| 28 |
``` |
| 29 |
cargo build --release |
| 30 |
cargo test --workspace |
| 31 |
``` |
| 32 |
|
| 33 |
The binary is `target/release/oxy`. |
| 34 |
|
| 35 |
## Quick start |
| 36 |
|
| 37 |
``` |
| 38 |
oxy identity create --name "Your Name" --email [email protected] |
| 39 |
oxy config --user core.sign change # sign every commit |
| 40 |
oxy init # in a project directory |
| 41 |
oxy status |
| 42 |
oxy commit -m "First change" |
| 43 |
oxy log |
| 44 |
``` |
| 45 |
|
| 46 |
Collaborating: |
| 47 |
|
| 48 |
``` |
| 49 |
oxy serve --root /srv/oxy --bind 0.0.0.0:8890 --tls-cert cert.pem --tls-key key.pem --token SECRET |
| 50 |
oxy clone https://host:8890/project |
| 51 |
oxy config remote.origin.token SECRET |
| 52 |
oxy push |
| 53 |
oxy pull |
| 54 |
``` |
| 55 |
|
| 56 |
Trust policy, so a server accepts only changes from keys you have granted: |
| 57 |
|
| 58 |
``` |
| 59 |
oxy policy init # your key becomes the root |
| 60 |
oxy identity export # a contributor sends you this file |
| 61 |
oxy policy grant alice.identity |
| 62 |
oxy push # publishes the policy |
| 63 |
``` |
| 64 |
|
| 65 |
## Layout |
| 66 |
|
| 67 |
|
| 68 |
|
| 69 |
| `crates/oxy-core` | Library: encoding, hashing, objects, the change graph, storage, identities, policy, protocol, repository operations | |
| 70 |
| `crates/oxy-server` | Reference HTTP(S) server for the wire protocol | |
| 71 |
| `src/cli` | The `oxy` command-line interface | |
| 72 |
| `docs/spec.md` | The specification | |
| 73 |
|
| 74 |
## Licence |
| 75 |
|
| 76 |
MIT or Apache-2.0, at your option. |