| 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, [docs/guide.md](docs/guide.md) for a user guide by task, and [docs/protocol.md](docs/protocol.md) if you are implementing a client or server. |
| 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 |
## Status |
| 17 |
|
| 18 |
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. |
| 19 |
|
| 20 |
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. |
| 21 |
|
| 22 |
## Install |
| 23 |
|
| 24 |
Builds for Linux, macOS, Windows and Haiku are on the [releases page](https://oxygenhub.io/andymccall/oxygen/releases). These are early releases: the macOS and Windows builds are not signed and have had little testing. |
| 25 |
|
| 26 |
- **Debian, Ubuntu and other Linux with apt** (x86_64, arm64 or riscv64): add the repository at https://oxygenhub.io/apt and install with apt, so `apt upgrade` keeps oxy current: |
| 27 |
|
| 28 |
```sh |
| 29 |
sudo curl -fsSLo /usr/share/keyrings/oxygenhub-archive-keyring.gpg https://oxygenhub.io/apt/oxygenhub.gpg |
| 30 |
sudo tee /etc/apt/sources.list.d/oxygenhub.sources >/dev/null <<EOF |
| 31 |
Types: deb |
| 32 |
URIs: https://oxygenhub.io/apt |
| 33 |
Suites: stable |
| 34 |
Components: main |
| 35 |
Signed-By: /usr/share/keyrings/oxygenhub-archive-keyring.gpg |
| 36 |
EOF |
| 37 |
sudo apt update && sudo apt install oxy |
| 38 |
``` |
| 39 |
|
| 40 |
Or download `oxy_VERSION_amd64.deb` (or `_arm64`, `_riscv64`) from a release and run `sudo apt install ./oxy_VERSION_amd64.deb`: from 0.3.1 it adds the repository by itself. It needs glibc 2.28 or later (Debian 10, Ubuntu 20.04 and newer). The repository's key is `82DD DD14 8BC9 0BDF 6006 09E9 522E 288F 265B DE6F`. |
| 41 |
- **Other Linux:** unpack `oxy-VERSION-linux-x86_64.tar.gz` (or `-linux-arm64`) and put `oxy` on your `PATH`. |
| 42 |
- **macOS** (Apple Silicon or Intel): unpack `oxy-VERSION-macos-arm64.tar.gz` (or `-macos-x86_64`), then `xattr -d com.apple.quarantine oxy`, since the build is not notarised, and put it on your `PATH`. |
| 43 |
- **Windows:** unzip `oxy-VERSION-windows-x86_64.zip` and put the folder on your `PATH`. SmartScreen may warn on first run, since the build is not signed. |
| 44 |
- **Haiku** (R1/beta6, x86_64): unpack `oxy-VERSION-haiku-x86_64.tar.gz` and copy `oxy` to `~/config/non-packaged/bin`. It is built in a Haiku guest rather than by OxygenFlow, so it has its own `SHA256SUMS-haiku` and no build attestation. |
| 45 |
|
| 46 |
`oh`, the OxygenHub command line, is released the same way from [OxygenHub's releases](https://oxygenhub.io/andymccall/oxygenhub/releases). |
| 47 |
|
| 48 |
Check a download against the release's `SHA256SUMS` with `sha256sum -c SHA256SUMS --ignore-missing`. |
| 49 |
|
| 50 |
## Building |
| 51 |
|
| 52 |
``` |
| 53 |
cargo build --release |
| 54 |
cargo test --workspace |
| 55 |
``` |
| 56 |
|
| 57 |
The binary is `target/release/oxy`. |
| 58 |
|
| 59 |
On Haiku, install `rust_bin` and `zstd_devel` with pkgman and build with `ZSTD_SYS_USE_PKG_CONFIG=1 cargo build --release`: zstd-sys then links Haiku's libzstd, since a system library also references zstd and ld refuses the bundled copy's hidden symbols. |
| 60 |
|
| 61 |
**Changelog:** a commit that changes code adds a line under `## Unreleased` in CHANGELOG.md (Added, Changed, Fixed or Security, with the issue number); versions change only at release. `scripts/changelog-check.sh [PATH...]` checks it for the paths a commit takes (the working copy's changes without any) and runs in the gate; `NO_CHANGELOG=1` for code changes users won't notice. |
| 62 |
|
| 63 |
## Quick start |
| 64 |
|
| 65 |
``` |
| 66 |
oxy identity create --name "Your Name" --email [email protected] |
| 67 |
oxy config --user core.sign change # sign every commit |
| 68 |
oxy init # in a project directory |
| 69 |
oxy status |
| 70 |
oxy commit -m "First change" |
| 71 |
oxy log # -n 10 for the latest ten, -v for full messages |
| 72 |
oxy log -r 'v0.3.1..main & author(me)' # a revset: set algebra over history |
| 73 |
``` |
| 74 |
|
| 75 |
Output uses colour, glyphs, and relative times on a UTF-8 terminal, and |
| 76 |
falls back to plain ASCII when piped, with `--plain`, or with `NO_COLOR` set. |
| 77 |
|
| 78 |
Collaborating through a hub such as OxygenHub: sign in once, in the |
| 79 |
browser, and every repository on that hub clones, fetches and pushes with it. |
| 80 |
|
| 81 |
``` |
| 82 |
oxy auth login https://oxygenhub.io |
| 83 |
oxy clone https://oxygenhub.io/owner/project |
| 84 |
oxy push |
| 85 |
oxy pull |
| 86 |
``` |
| 87 |
|
| 88 |
Or with your own server: |
| 89 |
|
| 90 |
``` |
| 91 |
oxy serve --root /srv/oxy --bind 0.0.0.0:8890 --tls-cert cert.pem --tls-key key.pem --token SECRET |
| 92 |
echo SECRET | oxy auth login https://host:8890 --with-token |
| 93 |
oxy clone https://host:8890/project |
| 94 |
``` |
| 95 |
|
| 96 |
A repository kept on your own storage, with no server in between (Oxygen |
| 97 |
Strata, see `docs/strata.md`): a bucket in your cloud account, in your |
| 98 |
region, under your keys, or a directory on a shared drive. |
| 99 |
|
| 100 |
``` |
| 101 |
oxy remote add cloud s3://my-bucket/repos/project --profile work # or gs://, az://, dir:// |
| 102 |
oxy remote check cloud # reachable, what it holds, and that it behaves |
| 103 |
oxy push cloud |
| 104 |
oxy clone s3://my-bucket/repos/project?profile=work |
| 105 |
``` |
| 106 |
|
| 107 |
Trust policy, so a server accepts only changes from keys you have granted: |
| 108 |
|
| 109 |
``` |
| 110 |
oxy policy init # your key becomes the root |
| 111 |
oxy identity export # a contributor sends you this file |
| 112 |
oxy policy grant alice.identity |
| 113 |
oxy push # publishes the policy |
| 114 |
``` |
| 115 |
|
| 116 |
Bookmarks (`oxy bookmark create|switch`, `oxy merge`), submodules (`oxy submodule add|update`), |
| 117 |
partial commits (`oxy commit PATH..`, `oxy commit -i`), `oxy blame`, `oxy bisect`, `oxy squash` and |
| 118 |
`oxy rebase` cover the everyday Git toolbox; see the guide. |
| 119 |
|
| 120 |
Working alongside Git: `oxy git import <repo> <dest>` converts a Git history, `oxy git fetch <url>` |
| 121 |
brings new commits of a Git remote into the bookmark, `oxy git push <url>` publishes the bookmark as |
| 122 |
commits on top of them, and `oxy git export <dir>` writes a plain Git mirror. |
| 123 |
|
| 124 |
Keys have a lifecycle: `oxy identity rotate` moves to a fresh key pair (the policy follows), |
| 125 |
`oxy identity renew --expires 365` sets an expiry, `oxy identity delegate add agent.identity --scope changes --expires 8h` |
| 126 |
lets another key sign changes for you (an AI agent, say) for a while without ever being able |
| 127 |
to move a bookmark, and `oxy identity revoke` retires a key. With several root |
| 128 |
keys, `oxy policy root add|remove|threshold` and `oxy policy sign` gather the required signatures |
| 129 |
through proposal files. |
| 130 |
|
| 131 |
## Layout |
| 132 |
|
| 133 |
|
| 134 |
|
| 135 |
| `crates/oxy-core` | Library: encoding, hashing, objects, the change graph, storage, identities, policy, protocol, repository operations | |
| 136 |
| `crates/oxy-server` | Reference HTTP(S) server for the wire protocol | |
| 137 |
| `crates/oxy-strata` | The S3, Google Cloud Storage and Azure stores a repository can be kept on | |
| 138 |
| `src/cli` | The `oxy` command-line interface | |
| 139 |
| `docs/spec.md` | The specification | |
| 140 |
| `docs/guide.md` | User guide, organised by task | |
| 141 |
| `docs/strata.md` | Keeping a repository on your own storage: S3, GCS, Azure, a directory | |
| 142 |
| `docs/protocol.md` | Wire protocol for other implementers | |
| 143 |
| `docs/prompt.md` | Shell prompt integration | |
| 144 |
|
| 145 |
## Licence |
| 146 |
|
| 147 |
MIT or Apache-2.0, at your option (see `LICENSE`). |