zit Command Reference

Writes .zit (the repository — a single, self-contained content log) and .zit-checkout (the working-state record) into directory (default: current dir; created if missing). The default branch trunk is unborn until the first commit. Artifacts are named with SHA3-256.

Creates DIR and its .zit, syncs the peer's artifacts down to convergence over HTTP. The origin's shun table is adopted with it (see shun), so a clone can never come up serving content its origin was ordered to remove; the adopted count is reported. URL is the peer's sync endpoint, used verbatim. Anonymous — no login. The URL is saved as DIR's default remote (canonical form — a user:password@host URL is stored as user@host, password structurally excluded), so pull/push/sync work with no URL. On a terminal, per-round progress shows on stderr with a closing rounds/bytes accounting line. Follow with zit open inside DIR to fill the working tree.

Materializes a check-in in the working tree — the second half of clone. Without CHECKIN, the tip of the main branch; with one (resolved like info — ID, prefix, branch, tag), that check-in directly, so a fresh clone opens straight at a release tag without materializing the tip first. An already-open tree is left untouched (use update to move it); a repo with no check-in is already correct and reported as such — though an explicit CHECKIN must resolve, so there it fails as not found.

Worktrees: --store=PATH in an empty directory opens a detached working tree of the repository at PATH (the checkout holding .zit, or the .zit file itself). The new tree keeps its own checkout state — branch, cone, undo, bisect — but reads and writes the one shared store, so a commit in either tree is immediately visible to the other; concurrent commits from different trees serialize on the store's own lock (writers queue, readers never block).

Re-open: on a tree that is already open, --store=NEWPATH re-points it instead — the rescue for a store that moved out from under its worktrees, uncommitted work intact. The new path must hold the same repository (one containing this tree's current check-in); re-pointing at an unrelated store is refused.

Records only which files to track — contents are read at commit time. Naming a directory adds every untracked file beneath it recursively; zit add . adds the whole tree. Control files are never added; re-adding a tracked file is a no-op.

Removes paths from the managed set so the next check-in records their deletion. By default the working copy is left on disk (unlike git). Removing an untracked path is an error; naming a directory forgets every tracked file beneath it.

Moves the working file, swaps the tracked-name entry, and records the rename for the next commit. OLD must be tracked and present; NEW must not be tracked or exist on disk — collisions are refused, no --force. Exactly two operands; never a glob, never a directory rename. Not undone by zit undo; reverse with zit mv NEW OLD.

Reports the branch, the current check-in, and each tracked file's standing in Fossil's words and column: ADDED (new, will enter the next check-in), EDITED (bytes or mode differ), MISSING (not in the working tree), CONFLICT under a pending merge, which is named as MERGED_WITH. Unchanged files are not listed. Doesn't report untracked files (extras) or deleted-and-forgotten files (diff).

Default output is Fossil's: an Index: banner per file, then unified hunks (three context lines, binary files noted). With --from/--to, compares two check-ins directly.

Every on-disk file under the checkout root that is neither tracked nor a control file — relative paths, one per line, sorted. Symlinks listed but never followed; directories themselves are not listed. Names beginning with a dot are hidden unless asked for.

Deletes the set extras lists. Destructive and not undoable. By default it refuses and only reports the count. Never prompts; tracked and control files are never touched; empty directories are not pruned. If both flags are given, --dry-run wins.

Adds everything extras lists and removes tracked files missing from disk (git spells it add -A). Never edits a working file; reports ADDED/REMOVED per action. Modified files are membership-unchanged and left alone.

Discards working-tree edits — all managed files, or just the named ones. Changes contents only, never tracking membership; a managed file the check-in doesn't contain is reported and left alone. Names each file it changes and, after a change, reminds you that zit undo can take you back.

Entries live in the local .zit-stash sidecar: durable user data, never synced, never an artifact — a reserved name, so it cannot be tracked. With no action, save runs. apply is fail-closed: the checkout must sit at the entry's own check-in and every target path must be clean — nothing is merged or overwritten. save, pop, and apply name the files they moved.

A landing is a ceremony, not a new artifact kind. The record is an ordinary forum thread, every comment and state change is a reply in that thread, and the outcome is a raw tag on the check-in that landed. A stock fossil clone reads all of it — the artifacts are ordinary; only the ceremony is zit’s. Nothing here mints a card that zit forum and zit tag do not already mint.

The record names a branch, not a frozen range. Check-ins added after the landing opens belong to it, which is what merging the target back into the branch while work continues requires. TARGET defaults to the repository’s main branch, and a branch may hold only one open landing at a time.

open’s message is split the way a commit message is: the first line becomes the record’s title — the thread’s H card, which is one token — and anything after it becomes the prose beneath. A one-line message is a title with no prose, and the record never carries the same text twice.

show also lists the check-ins on the branch that are not yet on the target — newest first, in topological order, so two made in the same second never invert — and the thread beneath them. A state change renders as an event (“dan rejected this”) rather than a remark, because that is what it is. Both lists are bounded, and say so when they truncate.

accept merges, commits, tags the outcome and records the transition, in that order: a failure part-way leaves merged work under a still-open landing, which one command settles, rather than an accepted record over an unmerged branch. In a checkout it requires that checkout to already sit on the target branch — moving it for you would be this verb rewriting a working tree it was not asked to touch.

With -R it needs no checkout of yours at all. It creates an ephemeral working area beside the store, materializing only the files both sides changed — every other path is resolved into the record without being written to disk — merges there, and removes it. The check-in is minted by the same code a checkout commit uses, so its F, P and R cards match what merging from a checkout would have produced. A landing that does not merge cleanly is refused with exit status 5, naming each conflicting path, and nothing is written: resolving a conflict is the author's job, from their own checkout. A server never holds a half-finished merge and never commits conflict markers.

accept reads the branch tip once and merges exactly that check-in, so a push arriving mid-accept is not swept into the merge. A caller that checked a tip — CI, a preflight — names it with --expect-tip HASH; if the branch has moved since, the accept is refused with exit status 6, nothing is written, and the message names the tip the branch is at now. The target is read once the same way, and merged onto by hash. A caller that judged the landing against a particular target names it with --expect-target HASH; if the target has moved, the accept is refused with exit status 7 and nothing is written.

When a merge produces a conflict whose bytes match one remembered here, the remembered resolution is used instead of writing markers into the working tree. Precedents live in the local .zit-precedent sidecar: never synced, never an artifact, invisible to fossil. Losing the file costs one hand resolution and nothing else, so damage degrades to “no precedents” rather than failing the merge — reported, never silent.

A precedent is keyed by the file path and the conflicted bytes together, which is exact: the conflict envelope carries all three sides. It is also whole-file, so a file whose other conflict changed will not replay. That under-fires on purpose — a resolution spliced into a neighbourhood that moved would be a plausible wrong answer written silently.

To decline replay for a single merge without forgetting anything, use zit merge --no-precedent.

Restores every affected file and the checkout record to their state before the last update or revert. Single level — a second undo in a row has nothing to undo. Does not recover clean, mv, or shun. Names each restored file on its own UNDO line (REDO for redo) before the confirmation.

Available only immediately after an undo; a new update or revert clears the redo slot.

Reads each tracked file straight from the working tree — nothing to stage. With no paths, everything tracked is captured; named paths commit just those (the rest carries forward). On success stdout carries check-in HASH on BRANCH; stderr carries the receipt — what went in (a.txt edited, or 3 files: 2 added, 1 edited) and a note: for every binary or CRLF file no glob declared, the thing Fossil would have prompted about. -q silences both.

The comment comes from -m, from -M FILE, or from an editor: with no -m on a terminal, commit opens $VISUAL (else $EDITOR, else --editor PROG) on a template whose # lines name the branch, the parent and every file this commit captures; those lines are stripped and an empty comment aborts. The template lives in .zit-ci-comment in the checkout root and stays there when the commit fails after the editor, so commit -M .zit-ci-comment retries without retyping. Off a terminal a missing -m is still a usage error.

Fork guard: a commit whose parent is no longer its branch's leaf is refused, naming the newer tip — zit update to join it, or --allow-fork to fork deliberately. With autosync on, commit pulls first (so the guard sees the freshest DAG) and pushes the new check-in after.

With sub-manifests enabled and pinned, a commit that drifts >15% from the analyzed optimum prints one advisory line (and interactively offers to retune) — never affects whether the commit succeeds.

CHECKIN resolves like info — full or abbreviated ID, branch, tag, or timestamp; --latest names the current branch's most recent check-in instead. With autosync on and a saved remote, pulls first so CHECKIN resolves against the freshest history. Recoverable with zit undo.

The receipt goes to stderr, so stdout stays clean for scripts: one line per file that moves (UPDATE, ADD, REMOVE; MERGE for a carried local edit, CONFLICT where the merge could not decide), then updated-from/updated-to with twelve-character hashes and weekday-dated times, the target's branch and comment, a count of changes, and the reminder that zit undo can take you back. -n prints the same receipt and changes nothing; -v lists unchanged files too.

Uncommitted work is carried across the move, not refused: every managed file is three-way merged (the check-in you are on, your working file, CHECKIN). So when a shared branch tip advances under you, update joins it with your edits on top, and the commit that follows is an ordinary child of that tip rather than a fork. Conflicts get markers in the files and a list on stderr, and update exits 1 so a script notices. A file you changed that CHECKIN deletes, or whose type changed, cannot be merged either way — update names it and refuses, changing nothing. To discard local changes instead of carrying them, run revert first.

Sparse cones: --cone replaces the checkout's stored cone (widening fetches newly covered content, demand-fetching through the saved remote when the store lacks it; narrowing dematerializes files without deleting stored content), --dense drops it and rematerializes everything. Absent flags inherit the stored cone.

With no arguments, prints the worktree cone's members one per line — exclusions in the cone-file grammar (!member) — or dense. add/remove compose the stored member set with the change and drive the same materialization path as update --cone at the current check-in, so an add demand-fetches missing content and a remove dematerializes. remove of an exclusion member re-widens. Removing every member is refused — return to dense with zit update --dense.

test answers "would this cone keep this path, and why" without materializing anything. Coverage is decided by the longest member covering the path, across both polarities — so the deciding member is often neither the first listed nor the one a gitignore last-match-wins habit would predict, and naming it is what makes the rule legible:

$ zit cone test src/a.zig src/vendor/big.bin src/vendor/keep/gem.txt README
covered src/a.zig                src
elided  src/vendor/big.bin       src/vendor
covered src/vendor/keep/gem.txt  src/vendor/keep
elided  README                   (no member covers)

The member prints bare, so it can be handed straight to zit cone remove; a named member under elided is necessarily an exclusion. A dense checkout reports covered … (dense), which keeps the exit status honest — the file really is there. Paths are validated as worktree paths first, so one that could never be tracked is a usage error rather than a silent elided. Exits 0 when every path is covered and 1 when any is elided, making it usable as a predicate: zit cone test build.zig && make.

Every tree registered against this store: the invoking tree (starred), every detached tree (open --store), and every co-located checkout that has opened or updated against it — each with its branch and check-in prefix. The registry is advisory and self-healing: trees stamp themselves at open and update, and the listing lazily prunes entries whose path is gone or whose checkout re-pointed at another store (membership is verified by the store file's inode, so a same-named impostor never counts). With -R it answers from anywhere with no working tree — "which trees does this store serve?". Move-safety warnings and cross-repo sweeps build on this data.

Three-way merge, recorded as a pending merge parent — run commit to record it. Conflicts get markers in the files and a list on stderr; resolve and commit, or undo to abandon. With autosync on, pulls first.

update is the reverse merge: the target brought into the proposed branch, on the store, as an ordinary merge check-in on that branch — GitHub’s Update branch, for a reviewer with no clone. It always merges in an ephemeral working area, checkout or not, so your own tree is never touched. A branch already carrying its target is left alone (exit 0); a conflict is refused with exit status 5, naming each path, and nothing is written — resolving it stays a clone’s job. The refresh is recorded as a reply in the record’s thread, so a clone sees it as part of the record. Refreshing a rung is what lets the rungs stacked above it probe and test against the combined state before anything lands.

Stacks (strata): a landing may target another branch that has its own open landing; that pair is a stack, read from the targets rather than stored anywhere. A stacked landing reviews only its own check-ins, because its diff is computed against the branch below it. Stacks land bottom-up: accept refuses a landing whose target has an open landing, was rejected, or already landed — in the last two the merge would succeed and file the work where trunk never sees it — and accepting one retargets whatever was stacked on it, which is the entire restack, since no check-in needs adjusting. Note that rejecting a landing rejects the proposal, not the code beneath a segment stacked on it: that branch descends from the rejected one and still contains its check-ins.

Uncommitted work does not block it. Your working file is the merge's “current” side, so a region only you changed stays yours and a region only NAME changed is applied around it. Where the two collide you get markers, exactly as for any other conflict, and undo restores the uncommitted bytes. A local change that cannot be merged either way — a symlink or directory where a file's bytes are needed — is named and refused before anything is written.

-X ours / -X theirs resolve every content conflict in favour of one side instead of writing markers — the mechanical cases, like a regenerated lockfile or a vendored tree taken whole from upstream, where resolving by hand is where mistakes enter. A region only one side changed is still that side's either way: -X answers only what the merge could not, so it is not “discard their work”, it is “stop asking me”.

-X ours is not --backout. --backout reverses NAME's change; -X ours keeps your side where the two collide and reverses nothing. They read alike and do different things.

One case -X deliberately declines: a file one side modified and the other deleted. That is a disagreement about whether the file should exist, not about its contents, and either reading silently destroys work — so it stays a conflict with or without -X. A strategy also leaves nothing for precedent to replay or record, since no conflict survives it.

Across a sparse cone: out-of-cone paths resolve at hash level with no blob reads — theirs-only changes are applied to the record (reported as "applied to the record"), ours-only carry forward, and only a path changed on both sides refuses, naming the path and the remedy (zit cone add … to widen).

A tag is one of two things, and --raw picks between them.

Without --raw, NAME is a symbolic name for one check-in (stored sym--prefixed): it resolves to that check-in everywhere a check-in name is accepted, and unlike a branch name later check-ins do not inherit it. Right for release names. Two check-ins carrying one name make that name ambiguous.

With --raw, NAME is written verbatim as a property, outside name resolution entirely — right for a fact many check-ins may carry, such as a CI verdict, optionally with a VALUE. Because raw tags are not names, plain list omits them; list --raw shows every tag with its prefix intact.

cancel retracts a tag, taking the same --raw choice as the add that created it. Names beginning wiki-, tkt-, or event- are refused — fossil crosslinks wiki pages, tickets, and technotes through them. ls aliases list; --no-cache and -R are accepted, and the write paths work against a bare store.

Mints one control artifact; history is never rewritten and the original check-in is untouched. At least one override flag is required.

Mark a known-bad and known-good check-in; zit narrows the candidate span and moves the working tree to the midpoint for you to test, until one check-in remains. Moves go through the update engine — refused over a dirty tree, recoverable with undo. State lives in .zit-checkout, never in the repository.

Depth-first P-card order from CHECKIN, resolved like info — full or abbreviated ID, branch, tag, or reserved form. Each check-in shown once; a missing referenced parent shows once as a phantom. With PATH (exact repo-relative path, not a pattern), shows only check-ins where that file's effective content changes — including add and delete.

--long adds each check-in's own facts after its id, so a file-history page is one invocation rather than a second call per row:

$ zit log --long tip readme.md
checkin 2b268f57…  2026-08-17T13:00:46.515  dmestas  third
checkin e35bda20…  2026-08-17T13:00:46.462  dmestas  second
checkin 347f4e8e…  2026-08-17T12:58:56.727  dmestas  seed

The comment is last because it is the only field that may contain spaces; a check-in with no comment prints an empty trailing field, so the column count never varies. An absent timestamp or user reads -. Works with and without PATH.

The default listing reads no artifact content. It walks the derived parent adjacency — the same relation Fossil keeps in its plink table and traverses by indexed query — so it costs the same on a 300 MB repository as on a small one. --long is different in kind: the timestamp, user and comment live only in each check-in's manifest, so that form reconstructs and parses every one. On a repository whose manifests inline the whole file set the gap is large — seconds against milliseconds — which is worth knowing before scripting --long over deep history.

Not an integrity check. log trusts what the derive already validated and does not re-hash the artifacts it names, so it will happily list a check-in whose stored bytes have since been damaged. verify is the verb that re-reads and re-hashes the store; Fossil draws the same line between traversal and test-integrity.

The --long record grammar — checkin <id> <timestamp> <user> <comment> — is a contract: consumers parse it positionally, and no display option, present or future, will change it.

Per line: short hash, ISO timestamp, branch, first comment line. Merges are marked M. Order is event time descending with hash tiebreak — byte-identical across runs.

Filters narrow the listing: -b BRANCH, -c (the checkout's branch), -p PATH (check-ins that change PATH against their primary parent), -u LOGIN; -r lists oldest first and --offset N skips the first N matches before -n counts. -F medium prints Fossil's shape — a date header once per day, then time, hash, *CURRENT* on the checkout's check-in, the comment, and (user: … tags: …); -F full adds each check-in's changed files, which -v adds to any format.

Check-ins with no same-branch child and no active closed tag; full ID plus branch, most-recent first, current checkout marked *.

One per line, by name, derived from active branch tags. Current checkout's branch marked *; a branch whose newest check-in is closed is marked (closed). Accepts --no-cache and -R.

<blob-id> <filename> per line in canonical order. VERSION resolves like info; omitted = current checkout (unborn is an error). Shows the effective set: delta check-ins are merged with their baseline, deletions omitted. Accepts --no-cache and -R.

--long adds three columns before the filename, which stays last so a name containing spaces is still unambiguous:

$ zit ls --long
f04f3b9b…  11  -  text    readme.md
980e8347…  4   -  binary  src/blob.bin
59df8a6e…  18  x  text    tools/run.sh

perm is the F card's own permission token — x executable, l symlink, - when the card carries none. It is the one fact no other verb can supply: it lives in the manifest, and the blob it names does not know it is executable, so without this a listing cannot mark executables and mis-renders a symlink (whose blob content is its target path). l reaches a repository only through import-fossil — zit commit refuses a symlink, matching fossil's allow-symlinks default.

class is text, binary (the content holds a NUL), or absent when the store cannot produce the bytes — a sparse elision, a shunned artifact, or a phantom. There size reads 0 because nothing was measured, not because the file is empty.

--size is the cheap half — <blob-id> <size> <perm> <filename>, no class column — and the split is exactly where the cost is. A size is read out of the frame header: a zlib frame states its uncompressed length outright, a delta carries its target size in its own header, so --size costs a header read per file and never resolves a delta chain. The binary verdict cannot be had that way, because it is "a NUL anywhere in the content" and the NUL may be the last byte. So a listing that needs names and sizes should ask for --size; one that needs the text/binary answer pays for --long. Under --size an unavailable blob prints absent in the size column, since there is no size to report.

--long reads every listed blob, so pair it with --under to pay only for what is displayed. The default two-field output reads no content and is unchanged.

Verbatim to stdout — no trailing newline added, binary passes through. Resolved against the effective file set (a delta check-in's own entry wins over the baseline; deletions read as not found). Emitted bytes are verified against the recorded hash. Accepts --no-cache and -R.

HASH is a full or ≥4-char hex prefix, resolved against every stored artifact including file blobs — branch/tag names not accepted (use info). Default is a summary: hash, size, type, per-card lines, Z self-checksum status. Accepts -R.

The incremental read seam for an external consumer that only speaks through the zit binary. Each artifact appended after CURSOR is emitted as a header line artifact HASH SIZE followed by exactly SIZE raw bytes (whole artifacts — delta storage is resolved and every payload is verified against its name; byte-identical to artifact HASH --raw), then one trailer line cursor CURSOR TOKEN. Pass both trailer values back on the next poll; they are opaque. Without --since, the full census streams (the bootstrap read).

--verify proves the already-consumed prefix is still byte-identical: appends (commits, sync arrivals) keep a cursor valid; a store rewrite (pack, a shun reclaim) fails validation — the cursor is dead and the consumer re-reads from zero (derived indexes rebuild; loss is detectable by design, never silent). Shun-masked artifacts and phantoms are skipped with the cursor still advancing.

--structural emits only artifacts that parse as structural artifacts — the same gate the repository’s own crosslink applies — and skips content blobs, which dominate a full stream’s bytes. Skipped frames are neither hashed nor emitted; the cursor still advances over them, so the flag never changes what a later poll sees and filtered and unfiltered polls compose against one cursor. A poll whose new frames are all content emits nothing and exits 3, trailer included.

Threads: this is the one verb that uses more than one. Reconstruction stays single-threaded — it memoises delta bases, and consecutive artifacts routinely share one — while the per-artifact hash check runs on up to min(cores, 8) workers over a bounded batch. Emission order, the payload bytes, and the exit codes are identical at any worker count; the only thing that varies is how many cores a full-history read will occupy.

Exit status departs from the global convention: 0 artifacts emitted, 3 cursor current with nothing new (trailer still printed), 4 cursor invalid — re-read from --since=0. 1/2 keep their usual meanings. Accepts -R — a bare indexer is the primary consumer.

Every check-in’s derived record, in persisted order: identity, timestamp, author, comment, tag operations, and the files changed relative to the primary parent — the answers an indexer otherwise re-derives by parsing and expanding every manifest itself. The first line names the stream format (crosslink 1); each record is a checkin header, an optional user line, a length-framed comment, tag lines, a cherrypick (+|-)HASH line per cherry-pick (+) or backout (-), file (A|M|D) lines, each followed under --lines by a lines ADDED REMOVED line, and end. A consumer skips a line it does not know. Free-text tokens are card-escaped exactly as an artifact carries them, so every line is newline-safe. A rename reads as a delete plus an add.

A record may say files unknown instead: a tree (sub-manifest) check-in, or a parent the store does not hold — the sqlite corpus carries exactly one, a 2009 check-in whose parent is genuinely absent. Unknown is deliberate; an empty change set is a claim, and the verb never claims what it did not compute.

A lines line, printed only with --lines, counts what the file added and removed against the primary parent, the way zit diff --numstat counts it, or says - - for a binary file; a mode-only change counts 0 0. It is left out when the store cannot produce the file’s content on either side, a shunned blob included. Each check-in is counted once and kept in a cache only this verb reads: the first --lines run over a long history pays one diff per changed file, later runs only for new check-ins, and a shun recounts only the check-ins that touch a path a shunned blob was written to.

Records are served from the derived cache when it provably covers the whole log (the same key-and-shun-fingerprint discipline every read verb follows) and derived from the log when it does not; --no-cache forces the derivation, and the two outputs are byte-identical — pinned by test.

Per line, Fossil's columns: the 12-character ID of the introducing check-in, its UTC ISO date, the line number (annotate) or the committing user (blame, praise), then the line. A line is attributed to the oldest check-in carrying it; a merged line is credited to its origin branch, never the merge itself. Only committed content is annotated; binary files are refused. VERSION resolves like cat's (omitted = the current checkout), so with -R and a VERSION no working tree is required — a bare store annotates at any check-in.

For each PATH the file's stored versions are walked newest-first, and every version whose content contains PATTERN is reported one line per matching line: <checkin12> <path>:<lineno>: <line>. A run of check-ins that did not touch PATH shares one blob and is reported once, not once per check-in.

This searches history, not the working tree — content that is not on disk, because it lives as deltas inside .zit. For the files in front of you, a dedicated tool such as ripgrep is faster than zit would be.

PATTERN is a literal string, not a regular expression: zit carries no regex engine. git log -S is literal for the same reason and is the closer analogue; matching fossil grep's POSIX expressions is later work.

A version whose bytes the store cannot produce — elided by a sparse store, shunned, or a phantom — is counted and reported on stderr rather than skipped silently: a search that quietly examined less than it claimed looks exactly like one that found nothing. Binary versions (any NUL byte) are not searched.

The pickaxes ask a different question: not "which versions contain this" but "when did it appear, and when did it go". They report one line per check-in, newest first — <checkin12> <±N|~N> <path>. A string added once and deleted later is exactly two lines, where plain grep reports every version that held it in between. PATH becomes optional and narrows the walk instead of driving it.

-S fires when the occurrence count changed; -G when a changed line mentions the pattern. Renaming x = SECRET to y = SECRET leaves the count at one, so -S is silent and -G is not — git draws the same line between its two pickaxes, and it is why both exist. Give one or the other, never both.

These are git log -S/-G. zit takes the string as the ordinary PATTERN operand rather than git's attached -S<string>, so there is one way to say it. Both read only the blobs that actually changed — a path whose content hash matches its parent's cannot have moved either answer — so the walk is far cheaper than a diff per revision. Merges compare against the primary parent only, as git does; counting against every parent would report one appearance twice.

Exit status departs from the convention: 0 at least one version matched, 1 nothing matched or the repository could not be read, 2 usage error.

Merges BRANCH into TARGET in memory, from the repository alone, and writes the result as plain files (--out DIR, which must be empty or absent) or as a gzip-compressed tar on stdout (--tar, no top-level directory). Nothing is written to the repository and no checkout is created, so a CI job can test a branch as merged without a clone, and without anything that could commit or push. It works with -R on a bare store; TARGET then has to be named.

One merge. This is the merge merge --probe judges and landing relies on: the files, contents and modes are what zit merge BRANCH leaves in a checkout of TARGET.

Conflicts are an answer. A pair that does not merge cleanly writes nothing, lists the conflicting paths on stdout one per line, and exits 5, the status landing accept gives the same finding. BRANCH already in TARGET writes TARGET's tree and says so on stderr; two unrelated check-ins are refused.

The tar depends only on the pair: canonical member order, the later of the two check-ins' times, no owner or host. A forge can cache it by the pair of tips.

The merge as JSON. -F json prints one document with the same exit status: the verdict (clean, up-to-date, conflict, unrelated), the base, current (TARGET) and other (BRANCH) check-ins, and every conflicting file. A file has a kind (text, binary, add-add, delete-modify, modify-delete, unreadable), each side's blob hash and mode, null where the path is absent, and for text the regions the merge found: same, current, other, both or conflict, each with half-open line ranges in base, current and other. The regions cover each file in order, so a page shows the merge region by region without merging again, and fetches the bytes with zit artifact. Which side is which is the caller's choice: to show a branch as "ours", name it as TARGET.

Recording the merge. --commit records the merge of BRANCH into TARGET on TARGET's branch, with an answer for each conflicting path: its resolved content at the same path under --resolved DIR, or --delete PATH. A clean merge needs no answers and takes none, so a forge can merge from the web without a checkout. Every other path is the merge's own. It writes nothing when the answers are not exactly the conflicting paths, when one still holds a conflict marker, or when TARGET or BRANCH is no longer the check-in named by --expect-current or --expect-other (exit 5, so a page knows to redraw). The check-in is the one zit merge and zit commit in a checkout would make with the same answers.

VERSION resolves like info. No working tree is involved and none is created — the file set is read straight from the repository, so -R works and a bare mirror can cut a release. Control files are never archived.

Modes travel. An F card's permission rides with the file: an executable stays executable and a symbolic link stays a link. A checkout-then-tar workaround routinely loses this, and the result looks perfectly correct — right files, right bytes — until someone unpacks it and ./configure will not run.

The bytes are reproducible. Members appear in the check-in's own canonical order, carry the check-in's own timestamp rather than the clock, and record no uid, gid, user name, or build host. Two runs of one VERSION on different machines produce identical files, which is what makes the output usable in a release pipeline.

Every member sits under one top-level directory. --name sets it; otherwise it is derived from OUTPUTFILE's basename with the archive suffix stripped (release-1.2.tar.gz gives release-1.2), falling back to the check-in's short id when there is no usable output name.

An OUTPUTFILE of /dev/null or the empty string writes nothing; with --list that is how you preview an archive. A file the store does not hold — a sparse store elides out-of-cone content — is refused by name before any bytes are written, never omitted, which would look exactly like success.

Identical to tarball in every respect but the container: same selection, same top-level directory rules, same reproducibility guarantee, and the same refusal to write a partial archive.

Modes travel in the central directory's external attributes — where a reader looks, and where an executable silently becomes 0644 if a writer gets it wrong. A member is deflated only when that makes it smaller, so an already-compressed file is stored rather than grown.

Members are limited to 4 GiB: zip64 is not emitted, and a file needing it is refused by name rather than written with a truncated size field. Use tarball for such a check-in.

Answers POST /xfer with an application/x-fossil body per the sync protocol; one request per connection, single-threaded. Binds 127.0.0.1. Stop with Ctrl-C. A running server picks up a concurrent shun or pack on its next request, no restart needed. A cone-scoped requester is served filtered; a sparse store refuses to be a clone origin for cones it does not cover (dense clone requests included) with one error card and no content — the requester's clone fails quoting the refusal. With --fronted, a trusted proxy on this machine is the only client, and its per-request X-Zit-Protect header — a glob list of branches whose membership that push may not change — is honoured: a pushed check-in that would join one, or a tag that would move a held check-in in or out of one, refuses the whole round with the branch named, on the same error card a content-policy refusal uses. The front decides who may change which branch and sends only the rule.

The front may also send X-Zit-Divert-Login with the login it authenticated. A push that would join a protected branch is then refused once, saying that the next push keeps the work on branch attempt/LOGIN/HASH; pushed again, it lands there instead, moved by a control artifact the server writes as zit-serve in the same commit, so the protected branch never shows it. The reply carries a message and a pragma zit-diverted, which a stock fossil prints as Server says and zit acts on by pulling the move, and an X-Zit-Diverted response header tells the front which check-in went where. Refusals are remembered for a week in .zit-cache. Without --fronted both headers are ignored and nothing about the server changes.

Announces what this repo holds, requests everything it lacks, converges toward the peer's content. With URL omitted the saved remote is used; neither is an error. A private repository is read the way it is written: with --user, a user@ in the URL, or the login a previous authenticated push or pull stored here, the pull authenticates as that login (sync §6); without any of the three it is anonymous.

Unversioned files are what a Fossil repository keeps without history: releases, downloads. These commands move them between the server at URL and plain files, with Fossil's own protocol, so the server can be quarry or a stock fossil server. Nothing is stored in this repository: quarry keeps them in its own storage, and sync, push, pull and clone leave them alone.

The newest time wins, as in Fossil. A push or rm no newer than the server's copy is refused with a message rather than silently ignored, and every change is confirmed against the server's catalog afterwards. Reading takes the o capability on the server, changing takes y; a server that shares nothing with this account says so. The login is the repository's, as for push, so run it inside the repository or name it with -R.

A name has no spaces, no . or .. parts and no leading /, and is at most 500 bytes; releases/1.2.3/x.tar.gz is one name.

Uploads every artifact the peer lacks until both converge; nothing on this side changes, except that when the server keeps a pushed check-in on an attempt branch (see zit serve) push pulls the move so this repository agrees. Anything the server says is printed as server: .... With URL omitted the saved remote is used. Without --user the push is anonymous; with it, a shared secret derived from the password signs the login card. After one successful authenticated push the derived secret (never the password) is saved at 0600, so later pushes need only --user.

One session, not pull-then-push: uploads what the peer lacks and receives what this side lacks until convergence. History transfers both ways and artifacts are never discarded — there is no force-push. Authentication works exactly like push.

A single default remote, not a named registry. No argument prints it (including what clone saved); URL saves it verbatim. Never put a credential in the URL — authenticate with --user on push/sync instead.

Bare lists every setting and its value; NAME prints one; NAME VALUE sets it. Every setting this verb edits is local to this repository and never crosses the wire — a clone comes up with defaults for all of them.

That is a deliberate line, not an omission. pgp-command is a command line this machine executes, so a value a peer could set would be remote code execution; fossil classifies it sensitive and propagates it nowhere, and clearsign sits in no configuration group at all. Settings that legitimately travel do so by other mechanisms — tracked .zit-settings/ files that clone like any other source, and the sync configuration groups.

One field value line per fact, read from the frames in .zit — nothing estimated: store/header/content/frame-overhead/config/shun/user bytes, artifact counts, and the full-form vs. delta partition of content bytes.

user-frames counts what the log physically holds — rows plus any supersede markers a pack has not yet reclaimed — so it can exceed the number of rows zit users prints.

Re-encodes full-form artifacts as deltas against their lineage and drops superseded config records; content and names are preserved exactly. Also where shunned content is reclaimed — reclamation is not reversible — and where a superseded user-table row goes away. Written to a temp file and swapped in atomically; transiently needs room for old + new store.

An artifact already stored as a profitable delta is copied verbatim, not re-encoded and compared. Re-beating every delta by a few bytes meant pack never reached a fixpoint: each run rewrote the whole store again for scraps. A delta that fails the profitability bar — a peer's poorly chosen base — is still re-based, so the verb keeps doing what its name promises.

A repeat pack over a store nothing has appended to answers immediately and rewrites nothing. Any commit, pull, or shun row re-arms it. A pack that answers this way streams no bytes and therefore checks no integrity — when a run does rewrite, it verifies every frame checksum and every reconstructed artifact hash along the way, but zit verify is the pass that always reads everything.

Two passes: every frame's whole-frame checksum (catches on-disk bitflips), then every artifact reconstructed through its delta chain and re-hashed against its name (catches valid checksums over wrong bytes). Read-only, lockless, safe against a live serve. An incomplete final frame from a crash is reported but is not a fault. Unreclaimed shunned artifacts are verified and labelled. On a sparse store the summary counts the cone's members and the deliberately elided artifacts, and verification abstains from checksums it cannot reconstruct without out-of-cone bytes — elision is never reported as damage.

Fossil's fossil configuration pull|import|merge|export. Configuration otherwise travels at clone time only, and that is deliberate: a shun table that refreshed on every sync would let any peer suppress content in this repository on its own say-so. This verb is how you ask for it anyway — explicitly, naming the area and the peer.

The shun area carries the peer's takedown records. Rows are added, never removed, so pulling cannot un-shun anything here. URL defaults to the saved remote; only configuration moves, no artifacts.

The user area carries the peer's logins, capabilities, and password hashes. Fossil serves it to an administrator only, so the pull is credentialed — --user=NAME with --password=SECRET or $ZIT_PASSWORD. Without them the peer answers with no rows and this verb says so rather than reporting an empty success. A pull merges (a row wins only if its mtime is newer), which is fossil's default; --overwrite replaces the local table instead, for a mirror tracking an upstream authoritatively. A local-only login survives a merge and does not survive an --overwrite.

import and merge read a file written by fossil configuration export AREA FILE, whose cards are byte-identical to what the sync protocol carries — so a fossil repository's user table reaches zit with no SQLite reader, no network, and no running server. import replaces the local table, merge folds rows in with the newest mtime winning; both are fossil's own two modes. Cards for areas zit does not model are counted and ignored. Read the result with zit users.

Shun rows in a file are added in both modes. Replacing the shun table would un-shun whatever the file does not name, and a shun is never undone here.

export writes an area in that same format, to FILE or to stdout when FILE is absent or - — so a table can be backed up before an import replaces it, and restored by importing the backup. The output carries no timestamp, so two exports of an unchanged table are the same bytes. The user area includes password hashes; treat the file as you would the repository.

One row per line, TAB-separated and sorted by login, so it reads by machine: LOGIN CAPS MTIME INFO, and with --raw the password hash after CAPS. The four category rows — nobody, anonymous, reader, developer — are ordinary rows of this table and are listed with the rest, exactly as fossil holds them.

zit users contact LOGIN prints a user’s contact, and with INFO sets it, as fossil user contact does. It is free text; zit git export takes the email address in it — the part in <…>, or the first word with an @ — as that user’s Git identity.

The hash is withheld unless asked for. It is the sync protocol's shared secret, and fossil serves the whole user area only to an administrator, so a listing that printed it by default would make it easier to lift here than from the repository this one mirrors.

CAPS is fossil's capability string, stored and printed verbatim. zit never interprets it: the vocabulary is fossil's to define, and a reader that parsed it would need changing every time fossil adds a letter. A repository that has never had a user table imported prints nothing and exits 0 — an empty table is a fact, not a failure.

A project can ship its own pre-commit checks as a tracked file, .zit-settings/before-commit, so they clone with the code and are reviewable in a diff. That file is inert on its own: zit never runs it until this checkout says so. Cloning a repository therefore executes nothing, and neither does pulling an edit to a check you already accepted — consent is pinned to the exact text you read, so any change revokes it and asks again.

Bare, it prints the command and its status and grants nothing: accepting something you have not been shown is not consent. Run it again with --yes to accept. A before-commit you set yourself with zit settings needs no trust record — writing the command is the consent.

The tool for the ordinary accident — an add . that swept in a build tree, noticed before anyone else has the check-in. Removed artifacts go to a local graveyard that purge undo restores and purge obliterate discards for good.

Not a takedown. A purge is local, so a peer that already holds the content keeps it and a later sync fetches it straight back. Use shun when the content must never exist here again. This is the trap the two verbs exist to keep apart.

A blob is removed only when no retained check-in still references it. A file the purged check-ins share with surviving history stays exactly where it is — removing it would not free anything, it would turn held content into a phantom the next update fails on. Tags naming a purged check-in go with it.

Only leaves can be purged, judged over the whole named set: zit purge checkins A B where B is A's child is accepted, because afterwards nothing points at either. Naming A alone is refused rather than orphaning B. The check-in your working tree is on cannot be purged at all — the one refusal with no override.

Reclaiming rewrites the store into a new generation and swaps it in atomically, exactly as pack does; a crash before the swap leaves the original untouched. The graveyard is local and disposable like the undo journal — never an artifact, never synced, not carried by a clone. Losing it costs recoverability, not data.

No tombstone is recorded, and that is precisely what makes a purge recoverable — and precisely why it is local. shun is the verb that also stops the content coming back.

Irreversible — undo does not recover it and the content cannot be re-fetched. By default it refuses and reports what would be destroyed; never prompts. Every sync direction honours the shun table (never requested, announced, served; arriving copies discarded). A hash not held here may still be shunned (given in full — a prefix can't be completed). The current checkout's check-in cannot be shunned. Removal rewrites the store atomically like pack; concurrent rewrites, or a store that changed mid-examination, refuse cleanly.

The table travels to clones. A clone of this repository adopts its shun table, and a clone from a Fossil server adopts that server's — over the same /shun configuration group Fossil uses, so the carriage is bidirectional with stock Fossil. This matters because shunning is a takedown mechanism: a clone that arrived without the table would, on its next sync with any third party, re-accept exactly the content an operator was ordered to remove.

The carriage is one-way and clone-time only. An ordinary pull or sync never changes this table, so a peer can never shun an artifact here on its own say-so.

A local, disposable accelerator letting from-scratch derivation skip the log's permanently flat prefix. Sidecar only: never writes the repository, never synced, never history; deleting it changes no answer and --no-cache bypasses it. Planted automatically by the first full derivation and advanced by the ordinary open path.

A sub-manifest lets a check-in carry its file set as a tree of shared, content-addressed slices instead of one flat F-card list. Emission is OFF by default; turning it on means peers below Fossil 2.29 are refused every S-bearing artifact, and it cannot retire artifacts already written. The specification is provisional; a repository containing one is a disposable test fixture. Settings are local and do not propagate to clones.

Transactional: DEST appears only after export, artifact creation, and ref publication all succeed. Branches are reconstructed from the commit graph, not the exporting refs: the main branch claims its whole first-parent chain to the root; other branches claim shallowest-tip first (name tiebreak) down first parents until reaching a claimed commit — so merges stay on the branch merged into, and history below a fork stays with the branch continuing through it.

Mirrors the canonical check-in graph through git fast-import — flat, sub-manifest, and delta-manifest history alike. Incremental and resumable: a local-only mark map in DEST/.zit-export-state makes re-runs export only new check-ins; deleting it costs a full re-export, never a wrong answer. A source holding S-card artifacts is a provisional-format fixture, and the exported mirror is disposable (noted once per run).

zit git export MIRROR exports new check-ins into the Git repository at MIRROR, the same incremental export as export-git, and remembers MIRROR in the repository’s config. A later bare zit git export then does the same from any checkout, a hook, a cron job, or a forge on a bare store with -R, as fossil git export does. With an autopush URL it pushes the main branch there afterwards, fast-forward only, to the remote branch main unless --push-branch names another. Everything given is remembered, and none of it is ever synced to peers.

An author’s address is the email in their contact in the user table (zit users contact), so a Git host links the commit to their account; without one it is login@DOMAIN. An autopush URL may not carry a password, since it is stored: use a Git credential helper or an SSH remote.

zit git status shows the mirror, the autopush URL, how many check-ins have been exported and when, and whether the main branch is current.

zit speaks fossil's sync protocol, so a stock fossil clones straight from zit serve — no converter, no verb. That is the export path, and it is verified on every CI run: scripts/roundtrip-fossil.sh takes a repository fossil → zit → fossil and compares the artifact sets, fossil's own test-integrity verdict, the event counts, and the shun table.

export-git exists because git speaks a different protocol entirely and needs fast-import. Fossil needs nothing.

What this route does not give you is a single .fossil file from one command — it needs a free port, a background process, a readiness wait, and a second binary. That gap is tracked separately.

The mode is the decision and it is permanent, so there is no default. SOURCE is the fossil's sync URL; --submanifest also accepts a flat zit store already cloned from it (the same operation as zit submanifest convert). DIR is created.

--compatible preserves the artifact corpus byte-exact: same hashes, same project code, flat manifests. The result is a first-class member of the origin's sync world — it pulls, pushes, and syncs with the fossil repository it came from. Fossil's sync protocol is the import path; no SQLite is ever read. This is the prerequisite for the eventual fossil → zit → fossil round trip: a later export reproduces the exact fossil, server settings aside.

--submanifest is a rebirth: every check-in re-mints as a sub-manifest tree under a NEW project code — uniform tree history from the first commit, at the price of a permanent break (never syncs with the origin; PGP signatures cannot survive rehashing and are stripped and counted; clusters drop). The partition parameter comes from --k, else from the §6.3 sweep over the source tip's names; each check-in's tree is then built from its parent's. Every (old, new) check-in pair is proven file-set-equivalent before anything is published, counts are reconciled against a full corpus census, publication is staged with an atomic rename as the only commit point (a failed run leaves a sweepable .zit-tmp-*, never a half-repo), and the old→new provenance map ships as a deterministic technote inside the result, so external hash citations stay resolvable by lookup.

The browser view — timeline graph, side-by-side diffs, file browser, annotate, branches — is quarry's single-repository local mode (quarry RFC 0010). This verb runs quarry ui <checkout root> QUARRY-ARGS... with the terminal inherited and returns its exit status; the binary is $ZIT_QUARRY when set, else quarry on PATH. When it cannot be started the verb says so and exits 1. Meanwhile zit diff --by renders a side-by-side page and zit timeline -F html renders the timeline.

Records a wiki artifact for title with the body read from stdin to EOF. Prints the new artifact hash — nothing else — on stdout. Cards per the artifact-format RFC: D (writer clock), L (title), N (only with --mimetype; readers assume Fossil wiki markup without it), U, W, Z. An empty title or author is refused.

Records a ticket-change artifact: one J card per field=value, sorted ascending (a repeated field is refused, not resolved by position), plus K, D, U, Z. new mints a fresh 40-hex ticket id and prints <ticket-id> <artifact-hash>; set requires an id some stored ticket artifact already carries — a typo'd id exits 1 instead of silently opening a second ticket — and prints the artifact hash.

post opens a new thread — --title is the thread's H card, the stdin body its W card. reply answers post-hash inside its thread, recording G (the thread root, resolved transitively — replying to a reply still names the root) and I (in-reply-to). An unknown post-hash exits 1; --title on a reply is refused (a forum artifact carries H or I, never both). Prints the new artifact hash on stdout.

Each post declares its own --mimetype (the N card); nothing propagates the thread root's to its replies, and omitting it leaves the card absent so the reader applies its own default.

Body from stdin. --event names an existing technote to record a new edit of (latest wins at read time); omitted, a fresh 40-hex event id is minted. --time sets the E card's own event timestamp (any form the artifact format accepts; default now); the D card is always the writer clock. Prints <event-id> <artifact-hash> on stdout.

--comment is the note's title (the C card), and it is what a timeline renders as the note's name. No later verb can attach it — a note recorded without one shows its event id forever — so give it at the mint or not at all. --tag adds a symbolic tag the note is found by, written T +sym-NAME * exactly as fossil writes it; repeatable, sorted into the ascending run the format requires. Names carrying whitespace, the same name twice, and an empty comment are all refused.

TARGET is a ticket, technote, or forum post's hash (full or abbreviated) or a wiki page's name; it is checked for shape only, as the format specifies — an unresolved target is recorded as a generic reference. add stores FILE as a blob, then an attachment artifact carrying one A NAME TARGET SOURCE card plus C, D, N, U, Z, and prints the artifact's hash, then the blob's, on two lines. FILE may be - for stdin, which needs --name. NAME defaults to FILE's final path component; a directory prefix is always discarded. An empty file is refused, as fossil refuses it.

rm writes an A card with no source for (TARGET, NAME): the association ends under the format's latest-wins rule; nothing leaves the store. list prints the live attachments — the newest A card per name, a sourceless one meaning gone — as NAME SIZE MIMETYPE BLOB DATE USER, with the target as a first column when no TARGET is given. A quarry attachment stub (a small text blob naming external bytes by SHA-256) is listed as external:sha256:… with the size and type it points at, and zit artifact describes such a blob as an attachment-stub.

The setting attachment-size-limit caps what add stores, in bytes, checked before the blob is written; 0 means unlimited. Fossil's default is unlimited; zit's, when the setting is unset, is 1 MiB — a blob in the DAG travels to every clone for ever. zit settings attachment-size-limit N raises it.