Skip to content
zit zit — Handoff
Login

zit — Handoff

Start-here document for anyone continuing the implementation. The scaffold is in place, builds clean, and tests pass. Nothing of the actual VCS is implemented yet beyond two foundational primitives.

What this is

zit is a Fossil version-control system written in Zig — a direct port from the specifications, not from Fossil's C source. The authority is the four Internet-Drafts frozen in docs/rfcs/ (.txt). Fossil's C source is used only as an oracle for byte-exact verification, never copied.

Current status

Area State
Project scaffold, build, CLI done — zig build, zig build test, zig build run -- version
src/delta.zig base-64 int codec (MSB-first) + checksum (mod 2³²), with RFC-derived tests. apply/create stubbed.
src/artifact.zig artifact naming (SHA-1/SHA3-256, lowercase hex) + Z-card MD5, with RFC example vectors. Card/type enums. parse stubbed.
src/repostate.zig skeleton: Rid, resolveName, currentTrunk stubs with the governing rules in doc comments.
src/sync.zig skeleton: ClientState (the §3.8 state machine), Client.step stub.

Everything marked "stub" returns error.NotImplemented and cites the RFC section that governs it.

Layout

build.zig, build.zig.zon      Zig 0.16 build (module "zit" + exe "zit")
src/root.zig                  library root; re-exports the four modules + aggregates tests
src/main.zig                  CLI entry
src/{delta,artifact,repostate,sync}.zig   one module per RFC
docs/rfcs/*.txt               the four frozen RFC finals (reference)
docs/HANDOFF.md               this file
.zit.fossil                   the Fossil repository (ignored; not tracked)

Build & test

Requires Zig 0.16+.

zig build                 # -> zig-out/bin/zit
zig build test            # unit tests
zig build run -- version

Implementation approach

  1. Test-first, one RFC rule at a time. Each rule becomes a test that cites its section, then the code to make it pass.
  2. Verify against the reference where a byte-exact check exists. fossil 2.28 is on PATH (/opt/homebrew/bin/fossil). The RFC examples were themselves re-captured from it; you can reproduce a manifest with fossil commit --user-override <u> --date-override <d> ... then fossil artifact current and compare bytes. The delta checksum and the SHA3/MD5 vectors in the current tests came from that reference.
  3. Layer order: delta -> artifact -> repostate -> sync. Don't start a layer before the one it depends on is real.

Suggested next steps (in order)

  1. delta.apply (RFC §4) — the decoder: parse header, copy/literal segments, trailer; enforce the enumerated rejection conditions; verify the checksum. This is the smallest self-contained deliverable and fully testable.
  2. delta.create (RFC §3, §5) — the encoder.
  3. artifact.parse (RFC §4, §5) — card tokenizer, ordering rules, per-type validity, Z/R verification, delta-manifest reconstruction (RFC §"Delta Manifest Reconstruction").
  4. repostate (RFC §3–§9) — DAG build, crosslink, tag propagation, leaves, symbolic-name resolution (pure max-mtime).
  5. sync (RFC §3–§11) — the client state machine, round dispatch, phantom resolution, clone, auth, config.

Scope

Version-control substrate only: check-in (manifest), cluster, tag/control artifact types; cards B C D F M N P Q R T U Z. The collaboration types (wiki, ticket, forum, attachment, technote — cards A E G H I J K L W) are carried opaquely (stored/transported by hash, not interpreted). This is a deliberate scope decision; the RFCs still describe the full set.

Fossil workflow

The repo lives in .zit.fossil inside the tree (ignored via .fossil-settings/ignore-glob). To work with a fresh clone of the directory:

fossil open --keep .zit.fossil    # establish a checkout without touching files
fossil status
fossil commit -m "..."            # commits land on trunk

Standard fossil: fossil timeline, fossil diff, fossil branch new, etc.

Zig 0.16 notes (things that changed and cost time)

References