How sync works

Code Folder Sync separates file identity, placement, and content. A rename can move one stable node without re-uploading its descendants, and a content edit can advance without turning into a path guess.

One folder, explicit repositories

A folder is one synchronization namespace. Its direct-child repositories and ignore rules are shared metadata. Every peer must agree before sync proceeds, so machines cannot silently scan different trees.

The saved-file path

1. A native watcher reports a path and waits for the stable-save window.
2. The peer uses lstat and captures only that leaf.
3. Immutable objects and one causal event enter the durable outbox.
4. New chunks and the event travel in one bounded publish exchange.
5. The hub commits objects, accepts the event, and assigns global order.
6. Other peers fetch missing objects, recheck local state, and apply.

Immutable content

Every object ID is the SHA-256 digest of its exact bytes. Small files use one chunk. Larger files use streaming content-defined chunks between 256 KiB and 4 MiB, with a target near 1 MiB. Localized edits usually reuse accepted chunks before and after the change.

Symlink manifests contain only the exact target string. Capture and apply never follow the link.

Causal ordering

Each mutation carries the entry and content versions it observed. The hub compares those bases in one SQLite transaction and assigns the canonical sequence. Wall clocks never choose a winner. Lost acknowledgements retry the exact event ID and peer sequence idempotently.

The Git plane

Ordinary path events exclude .git. Instead, a stable Git directory is captured as a content-addressed tree, checked withgit fsck --full, transferred incrementally, staged on the destination, checked again, and swapped under a recovery journal.

Reconciliation

Watchers improve latency but are not trusted as an event log. Startup, structural changes, overflow, ambiguity, and the periodic ten-minute deadline trigger a full metadata walk and checkpoint reconciliation. Unchanged file observations reuse accepted manifests; full verification intentionally rehashes content.