The sync model

Snapshots, the manifest, and the head

Every change to a vault produces a new snapshot — an immutable, signed commit of the entire tree at that moment. A snapshot points to a Vault Manifest: a Merkle tree of Nodes (files and directories) whose names and structure are encrypted under the Vault Key.

The vault's head is just a pointer to its latest snapshot. Your device also remembers its own base — the last snapshot it successfully synced — so mani sync always knows exactly what's changed since it last looked.

Push and pull

mani sync

sync does both halves in one command:

1. Pull — fetch any snapshots published since your base, and merge them into your local tree.
2. Push — if you have local changes, build a new snapshot from your base plus your edits, and publish it as the new head.

Publishing is a compare-and-swap (CAS-append): your device says "make snapshot N+1 the head, but only if the current head is still N." If someone else published first, the swap fails, your push is rejected, and you pull their snapshot before retrying — this is what keeps the snapshot chain linear and prevents silently clobbering a concurrent write.

Conflicts

If both you and another device edited the same file between your last pull and your push, plain CAS-append isn't enough — there's no single correct merge of two edited byte streams. Manifa keeps both: your version is kept as a numbered conflict copy next to the incoming one, and sync exits non-zero so scripts (and you) notice. Nothing is silently dropped.

Watching and the daemon

Running sync by hand works, but two commands run it for you continuously:

mani watch          # foreground, until Ctrl-C
mani daemon start   # background

Both watch the filesystem for local edits and the server for remote snapshots, and call the same push/pull cycle as mani sync — reaching quiescence (no pending local or remote changes) typically within seconds of an edit, not on a fixed poll interval.

Garbage collection

Deleted files and superseded chunk versions aren't deleted from the content-addressed store immediately — old snapshots may still reference them. The server periodically runs reachability GC: only chunks reachable from a snapshot still in a vault's retained history are kept.

Repairing local state

If local index corruption ever makes sync behave strangely — phantom conflicts, a false "already up to date" — mani repair rebuilds your local state from the server's published history. It adopts the server's version of everything, so run mani sync first if you have local edits you don't want to lose.