Tune automatic background sync

Auto-sync is on by default. What triggers it, what it will not do, and how to change it.

Written By Dustin

Last updated About 3 hours ago

TOVIO syncs opportunistically in the background, and it is on by default. Knowing that explains a lot of behaviour that otherwise looks like magic — and a couple of things that look like it is not working.

What triggers it

A successful command that advances history or a lane fires one background sync: commit, land, switch, checkout, tag creation, cherry-pick, revert, and rebase.

What it will never do

Fail your command. The sync is never fatal and is isolated from the operation that triggered it. A failed sync does not fail a commit.
Wait for a busy repository. It takes the write lock without blocking, and skips if another operation holds it.
Touch a dirty working copy. It skips rather than materialize over uncommitted work.
Resolve a conflict for you. Upstream integration folds in only what is conflict-free; anything else is left for a manual tovio land.
Advance a protected lane. Ever, automatically.

The settings

Setting	Default	Meaning
`sync.auto`	`on`	Whether background sync runs at all.
`sync.auto.push`	`shared`	The consent gate on the push leg. See below.
`sync.auto.interval`	`120`	Seconds between syncs. Floored at 5.
`sync.auto.mode`	`inline`	`inline` runs it in the command; `detached` runs it in a background child.

tovio config set sync.auto.push all

tovio config set sync.auto.interval 300

tovio config list

Value	What gets pushed
`off`	Nothing. Pull and integrate only.
`shared`	Only the current lane, and only after you have published that lane manually at least once. Never a protected lane. The default.
`all`	Every lane the ordinary push rules allow.

The shared default is why a brand-new lane does not appear on the remote on its own: publish it once with tovio sync, and it is tracked from then on. An unrecognised value falls back to the default rather than silently disabling the push.

Turning it off

tovio config set sync.auto off

tovio commit -m 'wip' --no-sync

--no-sync is a global flag and skips it for one command. TOVIO_NO_SYNC suppresses it persistently for a shell. Each setting also has an environment override — TOVIO_SYNC_AUTO, TOVIO_SYNC_AUTO_PUSH, TOVIO_SYNC_AUTO_INTERVAL, TOVIO_SYNC_AUTO_MODE — and the environment wins over the stored config.

Working offline

An inline sync against an unreachable relay pays a connect timeout, so after a transport failure the throttle backs off to roughly ten minutes rather than retrying every interval. A laptop on a plane stalls once, not repeatedly.

Where it syncs to, and what it integrates

The origin recorded at clone. The lane it integrates from is the current lane's upstream — the lane it will land onto, defaulted to the lane it was branched from:

tovio autosync upstream

tovio autosync upstream --set develop

tovio autosync upstream --unset

tovio autosync status

status reports the current configuration and throttle state, which is the fastest way to answer "why did it not sync?". autosync is plumbing rather than an everyday command, so it is gated out of the default tovio help index — tovio help --advanced lists it.

If you share that output, it names your remote address, repository id, and lane names. Redact whatever you would not publish.

The continuous form

Auto-sync is opportunistic — it needs you to run a command. tovio sync --watch is the daemon version, sharing the same pipeline on a timer so a repository stays current while idle.