Fossil, as a city

What you'll find here

Fossil is more than version control. It carries a wiki, a forum, a ticket system, and technotes, and serves them all through a built-in web server. There is even a small embedded scripting language, TH1. We visit this district last and lightly — it matters least for embedding the engine.

Key source

• src/wiki.c
• src/forum.c
• src/tkt.c
• src/cgi.c
• src/th.c

What you'll find here

A checkout is a directory of files plus a small .fslckout SQLite database tracking their state. Commit, merge, update, and status all live here. The checkout database is a separate thing from the repository database — a distinction worth getting straight early.

Key source

• src/checkin.c
• src/merge.c

What you'll find here

Fossil sync is HTTP POST under /xfer: two repositories trade artifacts, by hash, until both sides agree. The protocol is content-addressed — each side simply tells the other which hashes it holds.

Why it matters for the app

The planned app swaps Fossil's own socket code for a URLSession-backed transport, so the shape of the /xfer conversation is something we will need to know in detail.

Key source

• src/xfer.c
• www/sync.wiki

What you'll find here

Fossil is command-line-first C. A large Global struct holds process-wide state; commands are dispatched through a table; errors call exit(); output goes to stdio. Each of these assumptions has to be neutralized to run Fossil as an in-process library rather than a program.

Why it matters for the app

This is the amber district for a reason: most of the hard work of the planned FossilCore engine adapter lives right here. Globals, exit(), stdio — the whole adapter problem is an Engine Room problem.

Key source

• src/main.c
• src/dispatch.c

What you'll find here

Some artifacts are manifests — structured text listing the files of a check-in, its parent check-ins, and its tags. Manifests point at other manifests as parents, and the result is a directed graph: the history. Branches and tags are themselves artifacts. The timeline you see is this graph, walked.

Key source

• src/manifest.c
• src/timeline.c
• src/info.c

What you'll find here

Fossil stores content as artifacts: blobs of bytes, each identified by its hash. Storage is space-thrifty — an artifact can be kept as a delta against another artifact rather than in full. Nothing is ever mutated; history is append-only.

Why it matters for the app

That immutability is exactly what lets the app's offline cache be “correct by construction” — an artifact fetched once never changes, so it never needs invalidation.

Key source

• src/blob.c
• src/content.c
• src/manifest.c

What you'll find here

Not a metaphor. A .fossil file is literally a SQLite database — you can open it with the plain sqlite3 command-line tool and read its tables. The repository schema (tables such as blob, mlink, event, tagxref) is the real foundation. Understand this one fact and every district above it stops being mysterious.

Why it matters for the app

The embedded engine opens exactly these databases. And the app's own “library DB” is a separate SQLite store — so knowing where one ends and the other begins starts right here.

Key source

• src/db.c
• the repository schema