Documentation

# zit

> zit is a Fossil version-control system in Zig: one self-contained binary that reads and writes Fossil's artifact formats and speaks Fossil's sync protocol, so it clones from, pushes to, pulls from and serves stock `fossil`. A repository is a single store file, `.zit`, beside a working tree; there is no staging area and history is immutable. `zit help` lists every verb, `zit VERB --help` documents one, and any unambiguous prefix of a verb works. Exit status is 0 for success, 1 for an operational failure, 2 for a usage error.

## Getting started

- [Download](https://fossil.craftdesign.group/zit/uv/download.html): release binaries for macOS ARM64 and Linux x86-64/ARM64, with checksums and a source archive.
- [Fast clones for CI and agents](https://fossil.craftdesign.group/zit/doc/trunk/docs/fast-clones.md): the fastest way to a working clone: `zit clone URL work --horizon=tip --structural [--cone=PATH]` for the latest work, or `--horizon=HASH` when CI has the hash, then open, build, commit and push.
- [README](https://fossil.craftdesign.group/zit/doc/trunk/README.md): what zit does, what it leaves to Fossil, and how to build it.

## Essential verbs

- `zit clone URL [DIR] [--horizon=HASH|NAME [--depth=N] [--structural]] [--cone=PATH]`: copy a repository into DIR and open its working tree; `--no-open` leaves the bare store.
- `zit open [CHECKIN] [--cone=PATH]`: fill a cloned directory with a check-in's files.
- `zit update [CHECKIN]`: move the working tree to CHECKIN, or to the current branch's newest check-in, carrying local edits.
- `zit status`: the current check-in and each changed tracked file.
- `zit diff [--from A --to B] [PATH...]`: working tree against the current check-in, or two check-ins, as unified hunks.
- `zit commit -m MSG [--branch NAME] [--no-sync]`: record a check-in from the tracked files; `zit add` and `zit rm` choose which.
- `zit push [URL] [--user U]`: send the artifacts the peer lacks; the password comes from `ZIT_PASSWORD` or a prompt.
- `zit pull [URL]`: fetch the artifacts this repository lacks.
- `zit sync [URL]`: pull and push in one exchange.
- `zit timeline [-n N]`: check-ins, most recent first.
- `zit cat FILE [CHECKIN]`: a file's bytes at a check-in, to stdout.
- `zit merge NAME`: three-way merge NAME into the working tree; commit to record it, or `zit undo` to abandon it.

## Reference

- [Command reference](https://fossil.craftdesign.group/zit/doc/trunk/www/reference.html): every verb and flag, with the conventions they share.
- [Release notes 0.7.0](https://fossil.craftdesign.group/zit/doc/trunk/docs/RELEASE-NOTES-0.7.0.md): horizon clones, their measurements, and compatibility.

## Specifications

- [Artifact format](https://fossil.craftdesign.group/zit/doc/trunk/docs/rfcs/draft-fossil-artifact-format-00.txt): manifest and control-artifact cards, naming and checksums.
- [Delta format](https://fossil.craftdesign.group/zit/doc/trunk/docs/rfcs/draft-fossil-delta-format-00.txt): the byte-level delta encoding.
- [Repository state](https://fossil.craftdesign.group/zit/doc/trunk/docs/rfcs/draft-fossil-repo-state-00.txt): derived branches, tags and leaves.
- [Sync protocol](https://fossil.craftdesign.group/zit/doc/trunk/docs/rfcs/draft-fossil-sync-protocol-00.txt): HTTP clone and sync.
- [Sparse cones](https://fossil.craftdesign.group/zit/doc/trunk/docs/rfcs/draft-fossil-sparse-cone-00.txt): partial worktrees and sparse stores.
- [Horizons](https://fossil.craftdesign.group/zit/doc/trunk/docs/rfcs/draft-fossil-horizon-00.txt): content and structural horizon clones.
- [Sub-manifests](https://fossil.craftdesign.group/zit/doc/trunk/docs/rfcs/draft-fossil-submanifests-00.txt): tree manifests for wide repositories.