D 2026-10-13T02:27:51.614
L index
N text/x-markdown
U dmestas
W 3631
# go-libfossil
Pure Go library for working with [Fossil SCM](https://fossil-scm.org/) 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`:
``` pikchr
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](https://fossil.craftdesign.group/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 |
## Related
- **[EdgeSync](https://fossil.craftdesign.group/edgesync)** — Leaf agent + bridge built on this library
- **[Fossil SCM](https://fossil-scm.org/)** — The version control system this library speaks
## Clone
```
fossil clone https://fossil.craftdesign.group/go-libfossil go-libfossil.fossil
```
Z 6281c1cf0b6ae0fb6a4c5b19e15d260d