Overview

Artifact ID:	074843ad45cde69c6c8a81a6fbfe23cdd0946811026717a5492299e34de5a566
Page Name:	index
Date:	2026-10-13 02:27:51
Original User:	dmestas
Mimetype:	text/x-markdown

Content

go-libfossil

Pure Go library for working with Fossil SCM repositories. No CGo, no external dependencies beyond modernc.org/sqlite.

What It Does

Read, write, and sync Fossil repositories from Go — without shelling out to the fossil binary.

Create repos, store blobs, create checkins
Parse and serialize Fossil manifests (all 20 card types)
Encode/decode the xfer sync protocol (all 19 card types + zlib)
Run multi-round sync sessions against Fossil servers
Transport-agnostic — plug in HTTP, NATS, or your own transport

Package Structure

go-libfossil/
├── types.go, errors.go, julian.go   # foundation: FslID, TimeToJulian()
├── db/                               # SQLite wrapper: DB, Tx, Querier
├── hash/                             # content addressing: SHA1(), SHA3()
├── delta/                            # Fossil delta codec: Create(), Apply()
├── blob/                             # blob storage: Store(), Load(), Exists()
├── content/                          # delta chain expansion: Expand(), Verify()
├── repo/                             # repo lifecycle: Create(), Open(), Close()
├── testutil/                         # Fossil CLI oracle: HasFossil(), FossilRebuild()
├── deck/                             # manifest format (no DB): Parse(), Marshal()
├── manifest/                         # checkin ops: Checkin(), GetManifest(), ListFiles()
├── xfer/                             # sync wire format (no DB): EncodeCard(), DecodeCard()
└── sync/                             # sync engine: Sync(), Transport interface

Dependencies flow downward. deck/ and xfer/ have no database dependency — pure format layers.

Transport Interface

The sync engine uses a pluggable Transport:

    right
    SE: box "sync.Sync()" color white fill 0x6b5a2a width 1.3 height 0.45 rad 5px
    move 0.3
    I: box "Transport" color white fill 0x3a3a3a width 1.2 height 0.45 rad 5px
    arrow from SE.e to I.w color white thick

    HT: box "HTTP" color white fill 0x2a6b3a width 0.9 height 0.35 rad 5px \
        at 1.5 right of I + (0, 0.45)
    NT: box "NATS" color white fill 0x2a4a6b width 0.9 height 0.35 rad 5px \
        at 1.5 right of I
    MT: box "Mock" color white fill 0x3a3a3a width 0.9 height 0.35 rad 5px \
        at 1.5 right of I + (0, -0.45)

    arrow from I.e to HT.w color white
    arrow from I.e to NT.w color white thick
    arrow from I.e to MT.w color white

Built-in: HTTPTransport (talks to fossil server), MockTransport (testing). External: NATSTransport in EdgeSync leaf agent.

Protocol Notes

Fossil's blob_compress prepends a 4-byte big-endian size prefix before zlib data
HTTPTransport POSTs to the repo root URL — Fossil routes by Content-Type: application/x-fossil, not URL path
All 19 xfer card types supported

Performance (Apple M4 Pro)

Operation	Time
Checkin (10 files, 1KB each)	2.5ms
ListFiles (50 files)	52us
Deck Marshal (50 F-cards)	8.4us
Deck Parse (50 F-cards)	15us
Xfer Message Encode (50 cards)	62us
Xfer Message Decode (50 cards)	14us
Full sync round-trip	~150ms

EdgeSync — Leaf agent + bridge built on this library
Fossil SCM — The version control system this library speaks

Clone

fossil clone https://fossil.craftdesign.group/go-libfossil go-libfossil.fossil

Update of ”index”