Background sync

A checkout changes only when you run push or pull, unless you turn on a background mode. Each checkout has two independent modes:

One background process per user runs both modes for every registered checkout. It runs only while your machine or sandbox is on and you're signed in.

Follow remote changes with sync

wiele sync enable --directory ~/Wiele/acme
wiele sync status --directory ~/Wiele/acme

Sync pulls new revisions into the checkout. It changes only files you haven't edited. If a remote change would overwrite a local edit, sync turns off for that checkout and leaves both versions alone; run wiele status to see what's in the way, then enable sync again.

Pause sync before reading files that must not change underneath you, such as an agent's input:

wiele sync pause --directory ~/Wiele/acme --wait 30s
# read or copy the files
wiele sync resume --directory ~/Wiele/acme

pause waits for the current round to finish. If it's still running when the wait ends, the command fails with OPERATION_PENDING and pauses as soon as the round completes.

Upload edits automatically with live

wiele live enable --directory ~/Wiele/acme-draft

Live uploads stable edits to the checkout's branch. Once a file stops changing between two scans, live pushes the batch as one revision with the message Live file update. Live also publishes deletions of tracked files, so turn it on only where automatic publishing is what you want.

Live never writes to main. Use it on a copy, then merge the copy. Each branch has one live writer at a time. A second checkout of the same branch with live on waits, logging BRANCH_BUSY, until the first one stops.

If someone else pushes to the branch, live pulls their change before its next upload. If their change overlaps your local edits, live turns off and leaves both alone.

Sync and live can both run on the same checkout of a copy.

The background process

Turning on either mode starts the process. You can also control it directly:

wiele daemon status
wiele daemon logs
wiele daemon stop
wiele daemon start

daemon logs lists recent events with stable codes: uploads and downloads with their revision SHAs, pauses, and retries. It keeps the last 1,000 events and never records file names, contents or credentials.

To start the process at login, install it as a user service. This uses launchd on macOS and systemd on Linux:

wiele daemon install
wiele daemon uninstall

When background work stops

The process retries temporary problems on its own: network loss, a busy branch, a pending operation, rate limits and access changes in progress. Anything else turns off both modes for that checkout and logs the code, for example:

• AUTH_REQUIRED: sign in again, then enable the modes again.
• PAYMENT_REQUIRED: the organization's subscription needs attention.
• ACCESS_DENIED or NOT_FOUND: your access changed.
• RECOVERY_REQUIRED: run wiele status in the checkout and follow the fix it names.

Switching branches

wiele branch switch needs a clean checkout with sync paused and live off:

wiele sync pause --directory .
wiele live disable --directory .
wiele copy switch acme-rewrite
wiele sync resume --directory .

What "in sync" means

Sync catches up after the polling interval and the transfer time while you're online, signed in and free of conflicts. It isn't a shared drive with instant updates. Edits made offline stay local until the next round.