A Fossil repository engine that compiles to WebAssembly.

go-libfossil reads, writes and syncs Fossil repositories: the artifact format, the derived tables and the sync protocol, in Go without cgo. The same engine runs as a command-line tool, inside a server, in a browser tab, or inside a storage object at the edge.

$ go get github.com/danmestas/go-libfossil@latest
one check-in, three views · output of a real go-libfossil runsha3-256 · fossil 2.28 schema · sync protocol

1 · The artifact

A check-in is a text manifest. Its name is the hash of its bytes, so anything that names it pins its exact content.

Cplan\sthe\srelease comment
D2026-10-23T13:30:00.000 time
FREADME.md 39e24e73b262… file → blob
Fsrc/main.go 9a9719984127… unchanged
Pd62b0f181e52… parent check-in
Rbe8e6172c39c3f0aedf5b833b49f5df9 tree MD5
Uana user
Z1f37be8da8b9d9797176dcb9660b4359 card MD5
name = sha3-256(346 bytes) =
5f3eccd15aaaeccf576efd04f9c50a695e81a960cf0a7590bdf390624b8ba0c7

2 · The repository

Storing it derives the rows fossil derives, in fossil's own tables. fossil rebuild on the same blobs writes the same rows.

blob rid · uuid · size
5 · 5f3eccd15aaa… · 346
4 · 39e24e73b262… · 25
event type · objid · user · comment
ci · 5 · ana · plan the release
plink pid → cid · primary
3 → 5 · 1
mlink mid · fid · pid · file
5 · 4 · 1 · README.md
tagxref tag · value · rid
branch · trunk · 5
leaf rid
5

3 · The wire

A clone that has check-in 3 pulls. Each side announces what it holds; the client asks for what it lacks. Two rounds.

→ round 1
pull 52fdfc072182… 0ab0c192687b…
igot bd98d3f928c4…
igot 9a9719984127…
igot d62b0f181e52… # check-in 3
← reply
igot 39e24e73b262…
igot 5f3eccd15aaa… # new
→ round 2
pull 52fdfc072182… 0ab0c192687b…
igot bd98d3f928c4…
igot 9a9719984127…
igot d62b0f181e52… # check-in 3
gimme 39e24e73b262…
gimme 5f3eccd15aaa…
← reply
file 39e24e73b262… 25
file 5f3eccd15aaa… 346
igot 39e24e73b262…
igot 5f3eccd15aaa…
native · one static binary, no cgo
js/wasm · SQLite itself in wasm
TinyGo · whole API 1.3 MB gzipped
Where it runs

Version control inside the application, not beside it.

The repository is a SQLite database with Fossil's own tables, so wherever SQLite runs, so does the repository. A database/sql driver is the only thing a new host has to supply.

Server and CLI

One static binary

The libfossil command and the Go API build to a single binary for Linux, macOS and Windows, with no fossil installation and no C toolchain.

Serve repositories, mirror them, or read history from a build pipeline through typed Go values instead of parsed command output.

Browser

A repository in the page

Built for js/wasm with the ncruces SQLite driver, which ships SQLite itself as WebAssembly. A page holds a whole repository and syncs it with a server when it chooses to.

A document that explains a protocol can let its reader commit, branch, merge and sync in the page, and watch the tables change.

Edge storage

History next to the data

Built with TinyGo, the whole API fits inside a storage object that runs its own SQLite. Each request is one call into the engine inside one transaction, so it completes or leaves nothing behind.

A publishing tool can keep every revision of what it publishes as Fossil check-ins in the object that serves it, and show the history without a separate service.

Size

Small enough to ship with the page.

The whole public API, the HTTP sync client and signing included, built with TinyGo 0.43.0 is 1.3 MB compressed. The standard Go toolchain builds the same program about 3 times larger, which is still useful for debugging. A program that leaves out sync is smaller.

Measured from examples/tinygo: the TinyGo size is what CI builds on every change; the standard build is Go 1.27.3 with -ldflags='-s -w'. Under TinyGo a sync redirect ends the request with an error instead of being followed.

TinyGo 0.43.0, gzipped1.26 MB
Standard Go, gzipped4.06 MB
TinyGo 0.43.0, raw3.52 MB
Standard Go, raw16.1 MB
How we know it is right

Checked against the specification, requirement by requirement.

Fossil's behaviour is written down as a set of RFC drafts. The test suite turns each draft into a table of requirements and runs at least one case against every row; this table is that test's output, 636 of 636 requirements met.

DraftRequirementsMetNotes
Artifact format115115every card type, parse and write
Delta format4040compared with fossil's own output
Repository state9797derived tables match fossil rebuild
Sync protocol169169client and server
Sub-manifests7676extension, shared with zit
Sparse cones6363extension, shared with zit
Horizons7676extension, shared with zit

Against the real implementations

Interop tests run the fossil 2.28 binary and zit against go-libfossil in both directions: each clones, pulls and pushes the other's repositories, and each verifies what it received.

Deterministic simulation

Sync is also run in a seeded simulation that drops requests, truncates replies and partitions nodes. After each run it checks blob integrity, delta chains and convergence. Any failure replays exactly from its seed. The repository also carries seven fuzz targets.

Partial history

Hold the history you need.

A repository does not have to hold everything. A cone keeps the content of chosen paths. A horizon keeps history from a chosen check-in forward and leaves the rest on the origin, fetched only when an operation needs it. At the structural depth the clone also drops the manifests below the horizon and derives branch and tag state from a seed the origin signs.

A structural clone of fossil-scm.org's repository, 21,008 check-ins, takes about 30 seconds. How horizons work.

horizon Con the originheldCtrunkfeaturerelease
heldleft on the originhorizon, with a signed seed
Start

Open a repository and commit.

From the command line, or from Go. The libfossil command drives the same code as the library, and the file it writes is an ordinary Fossil repository: stock fossil reads it.

shell · the check-in name depends on the time
$ go install github.com/danmestas/go-libfossil/cmd/libfossil@latest
$ libfossil repo new notes.fossil
created repository: notes.fossil
$ mkdir work && cd work
$ libfossil -R ../notes.fossil repo open .
$ echo '# notes' > README.md
$ libfossil repo add README.md
ADDED    README.md
$ libfossil repo ci -m "first notes" --user ana
checkin <name> (rid=2)
$ fossil timeline -R ../notes.fossil
<time> [<name>] first notes (user: ana tags: trunk)
main.go
import (
  "github.com/danmestas/go-libfossil"
  _ "github.com/danmestas/go-libfossil/db/driver/modernc"
)

r, err := libfossil.Create("notes.fossil", libfossil.CreateOpts{User: "ana"})
// handle err
rid, uuid, err := r.Commit(libfossil.CommitOpts{
  Files:   []libfossil.FileToCommit{{Name: "README", Content: readme}},
  Comment: "first notes",
  User:    "ana",
})
// fossil open notes.fossil sees the same check-in.
What it is not
  • Not a replacement for the fossil binary's web interface, wiki or forum server.
  • Not a hosting service: it is a library and a command-line tool you run.
  • Not a Git bridge. It speaks Fossil's formats and protocol only.