For people who want to know what's under the hood: the object model, the chunking, and how Oak compares to the version control systems that influenced it. Oak is written in Rust; the CLI is a single binary.
Manifests and commits, like Mercurial#
Oak borrows its names from Mercurial: each commit points at a manifest, the full snapshot of the tree as (path, blob hash, mode) entries. The manifest is stored as one tree object per directory, as in Git, so a directory that didn't change between commits is shared by its hash rather than written again.
Everything is content-addressed with BLAKE3: a file's identity is its hash, so storing the same content twice costs nothing. Diffing two commits means walking two trees and skipping every directory whose hash matches.
Commits on a branch carry no message. The narrative lives on the branch, as its description, and only the squash commit that lands on main gets a message — derived from that description. The squash keeps a pointer to the branch's last commit, so the detailed history stays reachable without cluttering main.
Content-defined chunking with FastCDC#
Files are split into variable-length chunks with FastCDC. Chunk boundaries are chosen by the content itself rather than at fixed offsets, so inserting a line near the top of a 100 MB file changes only the chunks around the edit, not everything after it.
Git stores each version of a large file as a separate blob and relies on packfile delta compression after the fact. Oak chunks at write time, so deduplication is immediate and works across files: two assets that share a header share those chunks. Each chunk is hashed with BLAKE3, each blob records its ordered chunk list, and push and pull transfer only the chunks the other side is missing. On the server, chunks are stored once across every repo in an organization. A push still sends the content its repo doesn't already have, even when another repo in the organization stored it first: a repo can only point at, check for or read content it has published or sent itself, so knowing a file's hash never gets you its content.
Trust: the client verifies#
The client re-derives every commit's manifest hash from the entries the server sends, and rejects a mismatch. That's what makes clones and pulls trustworthy. To leave out directories you can't read under path rules, or didn't ask for with --path, the server sends a view: each commit rebuilt over the pruned tree, under its own hash, which the client checks the same way.
Local storage, like Fossil#
A local repository is a single SQLite database (.oak/oak.db) holding commits, manifests, and branch state, with large content stored as chunks — not a directory of loose objects.
How Oak differs from Fossil#
Fossil is the closest prior art in philosophy: a single local database file instead of a loose-object store, and a repository you can back up with cp. Where they diverge:
- Large files. Fossil stores content inline in SQLite, which caps out on large binaries. Oak chunks content and stores chunks by hash, so large assets are stored the same way as everything else.
- Object model. Fossil uses its own text artifact format. Oak uses manifests stored as content-addressed trees of directories.
- Branching. In Fossil a branch is a tag on a commit in a timeline. Oak has named branches with a parent, and branches are the unit of work.
- Scope. Fossil bundles a wiki, bug tracker, and forum. Oak stays close to version control, plus marks and access rules set per directory. No wiki, issue tracker, or forum; keep the tools you already use for those.
- Agents. Oak is built for branch-per-agent work: clone, commit on a personal branch, push. There's no separate pull-request object — the branch is the review unit, and its description is the change's story.
The server#
oak.space is a single Rust binary (Axum) with PostgreSQL for metadata and object storage for chunks, running in Oregon. The web UI is server-rendered HTML with htmx for partial updates — no client-side framework or JavaScript bundle.
Questions about the internals, or interested in working on Oak? Email [email protected] or join the Discord.