# 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](running.md#fossil-chat-bridge).
- **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.