README.md

Oxygen

Oxygen (oxy) is a distributed, commutative version control system written in Rust for large repositories. See docs/spec.md for the specification, docs/guide.md for a user guide by task, and docs/protocol.md if you are implementing a client or server.

It is self-hosting: this directory is an Oxygen repository, and the project's own history is kept with oxy, not with Git.

What is different

• 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.
• Conflicts are data. A conflicted state can be committed, pushed and pulled. Resolving one is an ordinary edit followed by a commit.
• Every change has a stable ID and a content hash. The ID survives rewrites; the hash makes history tamper-evident.
• 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.
• Every operation is undoable through an operation log.
• Large files are chunked with content-defined chunking into a BLAKE3-addressed store.

Status

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.

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.

Install

Builds for Linux, macOS and Windows are on the releases page. These are early releases: the macOS and Windows builds are not signed and have had little testing.

• Debian, Ubuntu and other Linux with apt (x86_64 or arm64): download oxy_VERSION_amd64.deb (or _arm64.deb) and run sudo apt install ./oxy_VERSION_amd64.deb. It needs glibc 2.28 or later (Debian 10, Ubuntu 20.04 and newer).
• Other Linux: unpack oxy-VERSION-linux-x86_64.tar.gz (or -linux-arm64) and put oxy on your PATH.
• 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.
• 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.

oh, the OxygenHub command line, is released the same way from OxygenHub's releases.

Check a download against the release's SHA256SUMS with sha256sum -c SHA256SUMS --ignore-missing.

Building

cargo build --release
cargo test --workspace

The binary is target/release/oxy.

Quick start

oxy identity create --name "Your Name" --email [email protected]
oxy config --user core.sign change      # sign every commit
oxy init                                 # in a project directory
oxy status
oxy commit -m "First change"
oxy log                                  # -n 10 for the latest ten, -v for full messages

Output uses colour, glyphs, and relative times on a UTF-8 terminal, and falls back to plain ASCII when piped, with --plain, or with NO_COLOR set.

Collaborating through a hub such as OxygenHub: sign in once, in the browser, and every repository on that hub clones, fetches and pushes with it.

oxy auth login https://oxygenhub.io
oxy clone https://oxygenhub.io/owner/project
oxy push
oxy pull

Or with your own server:

oxy serve --root /srv/oxy --bind 0.0.0.0:8890 --tls-cert cert.pem --tls-key key.pem --token SECRET
echo SECRET | oxy auth login https://host:8890 --with-token
oxy clone https://host:8890/project

Trust policy, so a server accepts only changes from keys you have granted:

oxy policy init                          # your key becomes the root
oxy identity export                      # a contributor sends you this file
oxy policy grant alice.identity
oxy push                                 # publishes the policy

Bookmarks (oxy bookmark create|switch, oxy merge), submodules (oxy submodule add|update), partial commits (oxy commit PATH.., oxy commit -i), oxy blame, oxy bisect, oxy squash and oxy rebase cover the everyday Git toolbox; see the guide.

Working alongside Git: oxy git import <repo> <dest> converts a Git history, oxy git fetch <url> brings new commits of a Git remote into the bookmark, oxy git push <url> publishes the bookmark as commits on top of them, and oxy git export <dir> writes a plain Git mirror.

Keys have a lifecycle: oxy identity rotate moves to a fresh key pair (the policy follows), oxy identity renew --expires 365 sets an expiry, oxy identity delegate add bot.identity lets another key sign for you, and oxy identity revoke retires a key. With several root keys, oxy policy root add|remove|threshold and oxy policy sign gather the required signatures through proposal files.

Layout

Licence

MIT or Apache-2.0, at your option (see LICENSE).