/sync

description: Synchronize issues with a configured Dolt remote
argument-hint: ""

`bd sync` runs one full synchronization cycle against the configured Dolt remote: pull, check for merge conflicts, recompute the denormalized `is_blocked` flag, then push — retrying a bounded number of times when another replica wins the push race. It is the loop a multi-machine deployment otherwise hand-rolls in shell, and it is the verb to reach for on a sync timer.

(This is not the old JSONL-era `bd sync`, which was removed in v0.51. Nested commands such as `bd backup sync` and the tracker-specific sync commands are separate commands and are unaffected.)

bd sync                  # sync with the default remote
bd sync --remote mini    # sync with a specific named remote
bd sync --attempts 5     # allow more push-race retries (default 3)
bd sync --json           # machine-parseable outcome

Exit codes are the machine contract, so a timer can branch on them without parsing output:

| Code | Meaning | |------|---------| | `0` | Synced, or nothing to do | | `1` | Error (transport, auth, storage) | | `2` | Merge conflict — halted, nothing pushed; resolve it by hand | | `3` | Push-race retries exhausted — transient, retry on the next tick |

Two properties are the point of the verb. Conflicts are detected **positively**, from the merge's own conflict rows and from Dolt's conflict tables — never inferred from the pull's exit status, which is untrustworthy in both directions. And a conflict sync cannot settle is **never** resolved by picking a side: it halts before recomputing or pushing, and keeps halting the same way until an operator resolves the divergence. (The pull underneath still auto-settles the convergent conflict classes it always has — machine-local metadata rows, audit-only dependency rows, last-write-wins on issue cells. Anything past those halts here.)

The halt message says which state the halt left behind, because it depends on the pull route and both are real: the SQL route aborts the conflicted merge and restores the working set, while the CLI/git-protocol route leaves the conflict rows **live** for you. A conflict that was already live when sync started — from an earlier halted sync or a hand-run merge — halts before the pull instead, and says that too.

The recompute between pull and push is not bookkeeping either — `is_blocked` is denormalized, so a dependency edge merged in from another replica leaves `bd ready` stale until it runs. It runs on every attempt, unconditionally: `bd recompute-blocked`'s full pass is specifically the repair that does *not* depend on a merge advancing HEAD, so it is what recovers a column left stale by a conflicted pull you resolved by hand — a state sync itself creates by exiting 2. Gating it on "did this tick merge anything" would mean that repair never runs again while every tick reports success.

This is not `bd federation sync`, which syncs with named peer towns and takes a `--strategy ours|theirs` to resolve whatever conflicts it meets. `bd sync` targets the configured remote and has no such switch.

`--json` reports `{"status", "attempts", "conflicts", "conflicts_live", "rows_corrected", "pushed"}` on every non-error exit; exit 1 emits bd's standard `{"error": ...}` envelope instead, so a timer reading `.status` must treat `null` as the error case (or just branch on the exit code, which is the point). A rig with no remote configured exits 0 with setup guidance; `dolt.local-only` and the `no-push` config flag are honored.

The equivalent by hand

# Before starting work or consuming changes from another clone
bd dolt pull

# After local issue updates and before handoff: commit, integrate, then publish
bd dolt commit
bd dolt pull
bd dolt push

`bd dolt commit` creates an explicit commit boundary when auto-commit is off or in batch mode; it is a safe no-op when there is nothing pending. The following pull integrates remote changes before the final push. The pull steps require a configured remote; use the one-time setup below first when needed.

Inspect the configured Dolt remotes with:

bd dolt remote list

If no Dolt remote exists, the project has a Git origin, and remote sync is enabled, `bd dolt push` automatically adopts that origin; do not add the matching URL manually. To use a distinct custom Dolt remote, first confirm that the chosen name is absent, then add it explicitly:

bd dolt remote add origin <distinct-dolt-remote-url>

Note

When enabled, `dolt.auto-commit` records successful writes in local Dolt history; it does not push them to a remote. Remote auto-push is a separate, opt-in setting and is disabled by default. Auto-push publishes committed HEAD only; it does not commit pending working-set writes when auto-commit is off or in batch mode. Keep an explicit commit boundary before handoff unless the project has a coordinated policy that provides one.