D 2026-09-07T15:56:51.357
L Home
N text/x-markdown
P 503ecff518a1173d00ff44584279e9e061fbd63644fb48fb45ed5f617165d248
U dmestas
W 5530
# 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.45in
D: box "delta" mono fit
arrow
A: box "artifact" mono fit
arrow
R: box "repostate" mono fit
arrow
S: box "sync" mono fit
M: box "submanifest" mono fit at A.s + (0.55in, -0.8in)
arrow from A.s down 0.25in then right until even with M.n then to M.n
arrow from M.e right until even with S.s then to S.s
C: box "cone" mono fit at R.s + (0.55in, -0.8in)
arrow from R.s down 0.25in then right until even with C.n then to C.n
arrow from C.e right until even with S.s then to S.s
```

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              # produce zig-out/bin/zit
    zig build run -- version
    zig build test         # unit tests, one cited test per RFC clause
    zig build smoke        # interop check against a fossil binary on PATH

## 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 dd9566c6391f2568f8c67db6deaa79ff