What is obsync's commit and push cadence?

[andyroberts2]

Part of #1

Question

What is obsync's commit and push cadence?

This is the core design question of the whole project. The vault must not drift far from the remote, but obsync must not produce a commit per keystroke — the history has to stay readable and the push rate reasonable.

To decide:

• How local change is detected. Filesystem watching (inotify/fanotify) vs. periodic git status polling, and what each costs on a large vault. Note that ignis already runs a chokidar watcher on the same tree.
• What "the user has stopped typing" means. Quiescence/debounce window, and whether there is a maximum wait so a continuously-edited vault still gets committed.
• Whether commit rate and push rate are the same knob. Committing often and pushing on a slower cadence is a real option, and keeps history granular without hammering the remote.
• Batching. One commit per settle window covering everything that changed, vs. per-file commits.
• Commit message format. obsidian-git defaults to vault backup: {{date}}; a summary of what changed is more useful but more work.
• Bounds. Behaviour on a huge burst (bulk import, plugin install, a paste of 500 files).

Prior art in docs/research/: obsidian-git's real defaults, and kubernetes/git-sync's --period / --sync-timeout / --max-failures model.

[andyroberts2]

Answer

One serialized sync loop, woken by a watcher or a 60s tick; git is the only source of truth about what changed.

The loop

A single serialized sync loop. Only one sync run is ever in flight. Each run:

git status --porcelain → commit if dirty → fetch → classify → push.

It is woken by either the filesystem watcher or a periodic tick.

Change detection is split by role: the watcher is a wake-up signal, never the change list. Every run asks git what actually changed. This is what keeps obsync correct against inotify dropping events under pressure, against watch-descriptor exhaustion on a large vault (ignis is already spending descriptors on the same tree), and — the case that decides it — against the third writer obsync cannot see, ignis's Headless Sync plugin spawning ob sync --continuous directly against vault files. A design that commits what the watcher reported is wrong in all three; a design that commits what git reports, merely woken by the watcher, degrades to a plain poller when the watcher fails and stays correct throughout.

Timing

Quiet window	10s	Clears ignis's write pipeline with margin — browser-side coalescing is 100ms quiet / 2000ms max-wait, then chokidar applies a 300ms stability threshold, so bytes can still be landing ~2.5s after the last keystroke. Anything under ~3s commits into a moving tree.
Max-wait cap	5 min	Bounds an unbroken hour of writing to ~12 commits instead of one per typing gap. This is the knob doing the real work on history readability.
Tick	60s, jittered	Bounds both "someone pushed from their laptop" and "the watcher dropped an event." Jittered because many sidecars will point at the same GitHub org.
Push floor	0 (off)	Optional lower bound on time between pushes.
Per-operation deadline	120s	Converts a hung git operation into a countable failure.
Network backoff	60s → 15m	Exponential, ceiling 15m, resets to 60s on any success.

The tick subsumes reconciliation. An earlier sketch had a separate ~5min "catch what the watcher missed" tick, but since every wake-up runs the whole loop, a fetch tick already reconciles and a reconciliation tick already fetches — two names for one timer. Folding them makes the reconciliation guarantee stronger (60s, not 5min), not weaker.

Commit rate and push rate are one knob, not two. Two independent timers would mean two schedulers racing for the same repo lock plus a persistent "committed but not pushed" state that the rest of the map then has to account for — #13 deciding whether that state is healthy, #6 classifying a branch that is ahead by design rather than by accident, and a restart mid-window working out whether those commits were ever meant to go out. At one-vault scale a push is a round trip and nothing else, so the granularity that would buy isn't worth carrying the state. The push floor is the escape hatch, and it is a rate limit on an existing loop rather than a second schedule.

Batching

One commit per sync run, covering everything git reports.

Per-file commits isolate the wrong unit. A note rename is a delete plus an add — split across two commits, neither is a rename and git's rename detection cannot see it. A note and the image pasted into it are one act. A plugin install touches a dozen files under .obsidian/plugins/<id>/ that are meaningless apart. Worse, every intermediate commit would be a state the vault was never actually in: a rename half-applied, a note referencing an attachment that does not exist yet. A batch commit per settle window is always a real snapshot.

Bursts

No burst mode. The max-wait cap is the only bound.

On a bulk import or a 500-file paste the quiet window is never reached, so the cap fires and commits a partial import. That outcome is mild and self-healing — a 30-minute import leaves ~6 commits, each an honest snapshot, converging to the right tree — and pushes stay cheap because each sends only new objects. The alternative (escalate the quiet window once the pending batch exceeds N paths) buys tidier history in a rare case and costs a threshold nobody can pick honestly: a plugin install trips it, a real import blows past it, and neither wants the same treatment.

Not decided here, because it is not cadence: a burst is also where content limits bite — GitHub's 100MB per-file hard limit, and whether attachments belong in git at all. That is #8's territory.

Failure

Local and network halves fail independently. The local half cannot fail for network reasons, so a dead remote degrades obsync to a local autocommitter that catches up when the network returns — the right behaviour for a homelab on a flaky uplink. Only the network half backs off.

Exponential backoff, not kubernetes/git-sync's flat retry. Flat retry is fine for a 10s pull loop; against an expired PAT it is 8,640 identical failures a day, which is log noise pretending to be resilience.

A hard deadline per git operation is not optional here. Because the loop is serialized, one hung git push against a black-holed connection would otherwise wedge commits, pulls, and the heartbeat indefinitely.

Never exit the process on sync failure. git-sync's --max-failures → exit(1) is wrong for a sidecar: exit means the restart policy restarts it, which does not fix a bad token, discards the backoff state, and turns a clearly-diagnosable stuck state into a crash loop that reads as "obsync is broken" rather than "your PAT expired." Exit non-zero only for startup config errors, where a restart cannot help either but the operator needs the container to visibly fail. Consecutive failures are still counted — that count is #13's input.

Commit messages

Summarise the change; provenance in the git identity; no date.

Single file changed:

Update Daily/2026-08-24.md

Otherwise:

Update 6 notes

+ Notes/Zettel/Bicameral mind.md
+ Attachments/diagram.png
~ Daily/2026-08-24.md
~ Notes/Index.md
- Archive/Old plan.md

• Subject names the file when exactly one changed, otherwise counts them.
• Verb varies with the operation — Update, Import 3,201 notes, Delete 4 notes. "vault backup" on a commit that deleted forty notes is actively misleading.
• Body lists paths with +/~/-, capped at 50 lines with … and 412 more beyond, so a bulk import does not produce a megabyte-long message.
• No date. obsidian-git's vault backup: {{date}} and simonthum's changes from $(uname -n) on $(date) both spend the whole message on metadata git already stores.
• Provenance goes in the author/committer identity (obsync <obsync@<hostname>>) — the field git has for it, and what git log --author filters on. The identity is a config knob, so it belongs to What is obsync's configuration and credential surface? #11; only the format is fixed here.
• No template tokens. obsidian-git needs {{date}}/{{hostname}} because a plugin cannot know what changed. obsync does know, and a user-editable template invites configuring your way back to a useless message.

Startup

Run the loop immediately on start, then fall into normal cadence. No init-phase knobs.

The reason the tree is dirty at startup is that obsync was not watching, so waiting to find out how far behind it is serves nobody. git-sync's --init-period/--init-max-failures exist because Kubernetes gates pod readiness on first successful sync; obsync has no such gate, and a second set of timing knobs is a second thing to misconfigure.

What is genuinely different about startup is a state distinction, not a cadence one: "never synced successfully since boot" should not read as "sync degraded" — a fresh install with a typo'd remote is a different problem from a healthy deployment that started failing. Flagged for #13.

---

Boundaries

Deliberately left to their own tickets:

• How do we guarantee we never commit a half-written note? #10 — the torn-write settle discipline. The quiet window here protects against a tree still churning; per-file "is this specific file mid-write" is How do we guarantee we never commit a half-written note? #10's.
• How does a human find out obsync has stopped working? #13 — surfacing failure, and the "never synced since boot" state. The 60s tick is the heartbeat it keys off; the consecutive-failure count is its input.
• What is obsync's configuration and credential surface? #11 — the commit identity as a config knob, and which of these values are exposed at all.
• What in the vault does obsync actually track? #8 — what gets tracked, content size limits, attachments and LFS.
• What is obsync's branch model and divergence handling? #6 — the classify step of the run, and everything downstream of divergence.

Vocabulary

This ticket introduced the words the rest of the map will use — sync run, tick, quiet window, max-wait cap, push floor, local half / network half, third writer. Captured in CONTEXT.md at the repo root.

[andyroberts2]

Resolved — see the resolution comment above. Unblocks #10 and #13.