# zit
[Fossil](https://fossil-scm.org)'s formats and sync protocol, reimplemented in
[Zig](https://ziglang.org) from their specifications.
zit is a library first — a Zig analog of libfossil: the delta encoding, the
artifact formats, derived repository state, and the HTTP sync protocol as a
clean, embeddable API. The `zit` binary is a thin CLI over that library.
The implementation is a direct port of five companion Internet-Drafts (frozen
reference copies in [`docs/rfcs/`](docs/rfcs/); errata the code implements
ahead of the published text sit beside them in
[`docs/rfcs/erratum/`](docs/rfcs/erratum/)):
| Module | RFC | What it specifies |
|--------|-----|-------------------|
| `delta` | `draft-fossil-delta-format-00` | byte-level delta encoding |
| `artifact` | `draft-fossil-artifact-format-00` | manifest / control-artifact card format, naming, checksums |
| `repostate` | `draft-fossil-repo-state-00` | derived branch / tag / leaf / current-trunk views |
| `submanifest` | `draft-fossil-submanifests-00` | S-card tree manifests: bounded per-commit manifest size for wide repositories |
| `sync` | `draft-fossil-sync-protocol-00` | HTTP sync / clone protocol |
Implementation follows the RFC dependency layering:
```
delta -> artifact -> repostate -> sync
\-> submanifest -/
```
## Design
The drafts are the authority, not Fossil's source. Test expectations come from
the spec text and its worked examples — every normative clause a module
implements gets a test citing its section. Fossil itself appears only in an
on-demand interop smoke check, which may confirm a spec-derived expectation but
never author one; a disagreement there means either zit misread the spec or the
spec is wrong, and the spec gets an erratum rather than the code a workaround.
No module touches ambient time, randomness, filesystem, or network; effects
arrive through injected interfaces. The sync client in particular is a pure
state machine — bytes in, bytes out — with transport supplied by the caller.
This keeps the library embeddable and makes the whole stack testable under
seeded deterministic simulation, where any failure replays exactly from its
seed.
## Scope
zit targets the **version-control substrate**: the check-in (manifest),
cluster, and tag/control artifact types. The collaboration types (wiki,
ticket, forum, attachment, technote) are carried opaquely — stored and
transported by hash, but not interpreted.
Beyond the substrate, the CLI carries Git interop in both directions
(`import-git`, `export-git`), sub-manifest adoption tooling with
replay-measured k selection (`submanifest analyze`/`enable`), a local rebuild
checkpoint that collapses cache-cold opens from minutes to seconds
(`checkpoint`), store reclamation (`shun`, `pack`), and an fsck (`verify`).
## What Fossil has that zit doesn't
Deliberate scope, not defects — zit is a substrate, not a Fossil replacement.
- **The collaboration layer.** Wiki, tickets, forum, technotes, and
attachments (and their `W` cards) are carried opaquely — stored and synced
by hash, never interpreted. The web UI (`fossil ui`) goes with them, as do
`stash`, `grep`, and `settings`.
- **Delta manifest writing.** zit reads fossil-authored delta (B-card)
manifests everywhere; its own writer emits flat or tree manifests today.
Planned: a repository whose history already carries delta manifests keeps
its dialect — commits there will emit deltas.
- **Manifest signing.** Signature wrappers are recognized and stripped on
read (§4.1.1); zit never signs what it commits.
- **SHA-1 repository creation.** SHA-1 history clones and reads fine; `zit
init` writes the sha3-256 naming policy only.
- **Unversioned-file management.** No `uv` verb; the uvfile sync vocabulary
is understood on the wire.
## What zit has that Fossil doesn't — and where compatibility breaks
- **Sub-manifests** (`draft-fossil-submanifests-00`): S-card tree manifests
bound per-commit manifest size on wide repositories, with adoption tooling
that replays the repository's own history to measure whether enabling pays
(`submanifest analyze` / `enable`, `import-git`'s k selection).
**This is the one compatibility break.** A repository that emits S-bearing
artifacts is permanently unreadable by stock Fossil (§8.1: disabling stops
new trees but cannot retire existing ones), and sync's peer-version gate
refuses to send trees to a pre-S peer rather than hand it artifacts it
would misread. Emission is off by default; enabling it — and `import-git`,
whose default imports as trees — states the spend.
- **The rebuild checkpoint** (`zit checkpoint`): a local, disposable sidecar
witness that collapses cache-cold opens from minutes to seconds on large
histories. Never stored, never synced; no wire or format impact.
- **A library-first, sans-IO architecture**: every module is embeddable and
runs under seeded deterministic simulation; the sync client is a pure
state machine.
Everything else round-trips with real Fossil in both directions — clone,
push, pull, and serve are exercised against a stock `fossil` binary in the
smoke suite, R checksums included. Where the code deliberately follows
Fossil's implemented behavior against the published draft text, the
divergence is documented in [`docs/rfcs/erratum/`](docs/rfcs/erratum/).
## Build
Requires Zig 0.16+.
```sh
zig build # build the `zit` binary into zig-out/bin/
zig build run -- version
zig build test # run unit tests
```
Further named steps: `zig build dst` (deterministic simulation, `--seed N` to
replay), `zig build fuzz -- <target> --seed N` (seeded fuzz targets),
`zig build bench` (benchmarks), `zig build cov` (kcov coverage report over the
test suite), and `zig build smoke` (interop check against a `fossil` binary on
PATH; run manually at milestones, never part of `test`).
## Source control
This project is itself under Fossil. The repository lives in `.zit.fossil`
(ignored); open a checkout with `fossil open --keep .zit.fossil`.