Hosting a repository

A repository on quarry is in one of four postures. The posture is chosen once, on the New repository form, and can be changed later from /fleet or the mirror.* ops. It decides who owns the history and which surfaces the forge offers. Everything else — visibility, chat, protected branches — is a setting that applies on top of whichever posture the repository is in.

The four postures

1. Native (start empty)

Quarry is the source of truth from the first push. Every surface is open: push with zit, land branches through landings, run CI, file tickets, edit the wiki and notes, post in the forum, chat. Trunk protection, auto-land and the gate tripwire all apply.

Nothing exists until somebody pushes, so an empty repository shows quick-start commands in place of a timeline. That is the only limitation.

2. Import and own

Clone an existing zit or Fossil server once, then cut the cord. From then on the repository behaves exactly like a native one; the badge beside its name reads forked from <host> and the upstream URL is kept only as provenance.

Implications:

• The upstream keeps moving without you. Nothing merges back, in either direction, unless you do it by hand.
• You can re-attach later from /fleet. Re-attaching merges whatever the upstream did in the meantime on top of local history, which can conflict like any other merge.

3. Mirror

Clone and keep pulling on an interval. Quarry pulls and never pushes. The interval is floored at 60 seconds: these upstreams are other people's servers, and the floor is a courtesy the form cannot opt out of. --mirror-tick (default 1m) is how often due-ness is evaluated, not how often anything is pulled.

By default a mirror refuses local writes — push, tickets, wiki, forum — because a write landing on a tracking store forks it by accident. The repository pages therefore hide the Landings, CI and Chat tabs and point readers at the upstream's own write surfaces.

Two hard limits before you rely on one:

• The store needs a working checkout. zit pull operates on a working directory, so a genuinely bare store cannot be mirrored. Stores created by zit clone or zit import-fossil carry one; this bites only hand-built bare stores.
• The upstream must allow anonymous clone. Some Fossil servers serve a browsable timeline while refusing sync (sqlite.org/lemon is one), and fossil clone exits 0 on that refusal. Check for the repository, not the exit status.

A failing mirror shows a red badge with the failure count on /fleet and on the repository page. A pull that brings nothing new does not re-index and is not logged.

4. Mirror that accepts writes

A site admin can flip a mirror to accept local writes (mirror.writes, or the switch on /fleet). The repository still tracks the upstream, so it now has two write heads: the next scheduled pull merges upstream on top of whatever landed locally. Landings, CI and Chat stay hidden while the repository tracks.

This is a transition state, not somewhere to live. When the upstream is done being the upstream, detach — that turns the repository into posture 2 cleanly and stops the pulls.

Settings that cut across every posture

• Private. Only accounts holding a role on the repository can see that it exists. Everything else is readable by anonymous by default, per the repository's Fossil capability letters (RFC 0004).
• Chat. A per-repository switch in settings. Off on mirrors regardless of the switch. When off, the Chat tab and the entry in the chat side rail disappear for everyone.
• Protected branches. An owner plus required checks on trunk (RFC 0007). A store-level zit landing accept can still walk past the forge; the gate tripwire on the CI page reports every check-in that reached a protected branch outside a landing.
• Fossil chat bridge. A mirror of a Fossil server can bridge one channel to that server's chat. The upstream needs a login with the C capability and http_authentication_ok set. No edits or mentions cross, and each Fossil server is its own chat — see running.md.
• Fossil clients. A repository cloned from Fossil advertises a fossil clone command alongside the zit one; the wire format is shared, so readers who already have fossil need not install anything.

Operational notes

• A store dropped into the data directory is served as starting, with a 503 page that refreshes itself, until its index is built. A large import does not block the rest of the forge.
• Pulls take the store's single-writer lease, so several nodes can serve one store safely.
• The exit hatch is the same in every posture: zit clone. Nothing is held hostage in the index, which quarry reindex rebuilds from the store at any time.