D 2026-09-07T15:58:29.001
L Home
N text/x-markdown
P 12d5ccdb990c1f56a6d54fba55a9abe641e4ba9702bc92d657ba8e07290545dc
U dmestas
W 5654
# zit
A Fossil version-control system in Zig.
zit reads and writes Fossil's artifacts and speaks Fossil's sync protocol,
so it clones from, pushes to, pulls from, and serves stock `fossil`, and a
checkout means the same thing to both tools. It is written from the
specifications, not ported from C: six Internet-Drafts frozen in this
repository are the authority, and Fossil itself appears only in the
differential tests that hold the two implementations to the same answer.
The `zit` binary is a thin command over a library — a Zig counterpart to
libfossil — whose modules take no ambient time, randomness, filesystem, or
network, so the whole stack runs under seeded deterministic simulation.
## Download
[Download Zit 0.3.8 for macOS ARM64 or Linux x86-64/ARM64, or get the source archive](uv/download.html?v=0.3.8), or read the [release notes](doc/version-0.3.8/docs/RELEASE-NOTES-0.3.8.md).
Releases are also mirrored to [GitHub](https://github.com/danmestas/zit/releases).
## What it does
The everyday verbs — `init`, `add`, `commit`, `update`, `merge`, `diff`,
`status`, `timeline`, `branch`, `tag`, `annotate`, `grep`, `bisect`,
`stash`, `undo`/`redo`, `clone`, `push`, `pull`, `sync`, `serve` — with
Fossil's output shapes and Fossil's settings: `.fossil-settings/` is read
at every tier, `ignore-glob`, `clean-glob`, `manifest`, and the rest mean
what they mean in Fossil.
Beyond that:
* **Git in both directions** — `import-git` and `export-git`.
* **Sub-manifests** — bounded per-commit manifest size for wide
repositories (`submanifest analyze` / `enable`). Off by default; a
repository that turns them on is no longer readable by stock Fossil, and
sync refuses to hand such artifacts to a peer that would misread them.
* **Sparse cones** — partial worktrees (`open --cone`, `cone`).
* **Indexer feeds** — `frames` and `crosslink` stream raw artifacts and
derived per-check-in records from a cursor, for a forge or search index.
* **Store care** — `verify`, `pack`, `purge`, `shun`, and a local rebuild
`checkpoint` that keeps cache-cold opens fast on large histories.
## What it leaves to Fossil
By decision, not omission. The collaboration artifacts — wiki, tickets,
forum, technotes, attachments — are stored and synced by hash but never
interpreted, and the web UI goes with them (`zit ui` hands off to a forge that
serves the repository). There is no unversioned-file
store; a peer's unversioned files are declined visibly. zit never signs a
manifest and never creates a SHA-1 repository, though it reads both.
## The specifications
The drafts under [docs/rfcs](dir?ci=trunk&name=docs/rfcs) are the sole
authority. Expected values in tests come from the spec text and its worked
examples, never from observing another implementation; where the code
follows Fossil's implemented behaviour against the published text, the
divergence is recorded in [docs/rfcs/erratum](dir?ci=trunk&name=docs/rfcs/erratum).
| Layer | Draft | Specifies |
|-------|-------|-----------|
| `delta` | [draft-fossil-delta-format-00](doc/trunk/docs/rfcs/draft-fossil-delta-format-00.txt) | byte-level delta encoding: copy/literal segments, base-64 integers, mod-2³² checksum |
| `artifact` | [draft-fossil-artifact-format-00](doc/trunk/docs/rfcs/draft-fossil-artifact-format-00.txt) | card-structured manifests and control artifacts, content addressing (SHA-1 / SHA3-256), checksums |
| `repostate` | [draft-fossil-repo-state-00](doc/trunk/docs/rfcs/draft-fossil-repo-state-00.txt) | branch, tag, and leaf state derived from the append-only artifact set |
| `submanifest` | [draft-fossil-submanifests-00](doc/trunk/docs/rfcs/draft-fossil-submanifests-00.txt) | S-card tree manifests: bounded per-commit manifest size for wide repositories |
| `sync` | [draft-fossil-sync-protocol-00](doc/trunk/docs/rfcs/draft-fossil-sync-protocol-00.txt) | HTTP replication of the artifact set between repositories |
| `cone` | [draft-fossil-sparse-cone-00](doc/trunk/docs/rfcs/draft-fossil-sparse-cone-00.txt) | sparse cones: partial worktrees and the sparse-store path for monorepos |
Each layer depends only on the layers before it:
```pikchr center
boxwid = 1.1in; boxht = 0.45in; movewid = 0.5in
D: box "delta" mono fit
arrow
A: box "artifact" mono fit
arrow
R: box "repostate" mono fit
arrow
S: box "sync" mono fit
C: box "cone" mono fit with .n at R.s + (0, -0.4in)
arrow from R.s to C.n
arrow from C.e right until even with S.s - (0.18in, 0) then up to S.s - (0.18in, 0)
M: box "submanifest" mono fit with .n at A.s + (0, -0.95in)
arrow from A.s to M.n
arrow from M.e right until even with S.s + (0.18in, 0) then up to S.s + (0.18in, 0)
```
That ordering is also the implementation order, and [src](dir?ci=trunk&name=src)
mirrors it module for module.
## Building
Requires Zig 0.16 or later.
zig build --release=fast # the shipped binary, at zig-out/bin/zit
zig-out/bin/zit version
zig build test # unit tests, one cited test per RFC clause
zig build smoke # interop check against a fossil binary on PATH
`--release=fast` is what the release builds use; a plain `zig build` is a
Debug binary, many times slower on a real history.
## Finding your way
* [Timeline](timeline) — current activity and history
* [Source tree](dir?ci=trunk) — browse the code at trunk
* [README](doc/trunk/README.md) — design notes, scope, and build steps
* [Release notes](dir?ci=trunk&name=docs&re=RELEASE-NOTES) — every release, oldest to newest
* [docs/rfcs](dir?ci=trunk&name=docs/rfcs) — the six frozen drafts
* [GitHub mirror](https://github.com/danmestas/zit) — issues and CI
Z f95a42eb1fd0c21848c23a8d32f77d2b