retrofit reconcile
retrofit reconcile closes a fork: two or more ops that share a
prev=, as a merge of two branches that each added ops leaves them
(When two branches change the oplog).
It picks an order for the forked blocks and rewrites prev= into one
chain, and every op keeps its opid.
Merge branches that change the oplog is the task
guide.
Synopsis
From retrofit reconcile --help:
Usage:
retrofit reconcile [<fork-selector>] [flags]
Description
With no mode flag, reconcile reports each fork and whether a clean order
exists, and writes nothing. --clean and
--accept-dirty write. retrofit reconcile --help-all gives the bias,
strictness and selection flags, how a fork of three or more blocks
closes, and the three-file mode, and the
Output contract gives each mode’s text and JSON.
Selecting a fork
A <fork-selector> is a prefix of the fork’s shared prev=, four hex
characters or more. One shorter, or one no fork’s prev= starts with,
refuses fork-selector-unknown, and one that two forks’ prev= start
with refuses fork-selector-ambiguous. The bare report covers every
fork, or the one a selector names.
A write needs no selector on an oplog with one fork. With two or more it
refuses fork-selector-ambiguous unless a selector or --all names what
to close. On an oplog with no fork, a write with no selector exits 0 and
writes nothing. --all with a selector or with --accept-dirty, and
--keep or --swap with no mode flag outside the three-file mode,
refuse flag-conflict.
Forks of three or more blocks
A fork of three or more blocks closes two blocks at a time. A run that
stops refuses with the stopping step’s own code (fork-no-clean when
that pair has no clean order), and its message names the step and the
two blocks’ first ops.
The same op on two clones
Two developers on two clones who run the same op add against the same
predecessor mint two different opids, so merge=union keeps both lines
and the merge leaves a fork holding the same act twice. Neither act is
lost. Either order charges the second copy against the rule that governs
it (rule-unique-name-in for a CreateTable, and so on), so reconcile --clean refuses it with fork-no-clean. --accept-dirty writes an
order anyway, and op revise or op remove resolves the tail it
leaves.
Orders that replay one way only
An index key expression, an index predicate, or a CHECK reads only
columns of its own table. One block’s CreateIndex on lower(email)
and the other block’s ExtractTable moving email into a new table
are clean in one order only. With the extract first, the index names a
column its table no longer holds, so that order replays with
rule-exists-and-alive. --clean refuses that order and accepts the
other, in which the extract moves the index to the new table.
A close whose order is forced this way, or forced by a Seal, and whose
override report is not empty, is not written by a bare reconcile --clean:
it refuses fork-forced-order. Re-run with the flag that names the forced
order (--keep or --swap, as the refusal says) to consent to it.
Options
From retrofit reconcile --help:
Flags:
--accept-dirty write the requested order even when no clean order exists (dirty tail; resolve with op revise)
--all reconcile every leaf fork in line order (per-leaf atomic write); with --clean, halts with fork-nested (exit 1) at a fork whose block holds a nested fork, as two forks in one oplog present; run reconcile <fork-selector> --clean on the nested fork first, then on the enclosing one
--allow-sealed-rewrite opid [sealed history] attest each Seal this run would demote or replace, by its full opid (repeatable, comma-separated); a value attests the Seal it names and selects nothing, and a Seal left unnamed refuses seal-removal-refused
--base <file> three-file merge: the oplog your branch forked from main with <file>
--clean write only if a clean order exists; refuse otherwise
-h, --help help for reconcile
--help-all show extended help (vocabulary, semantics, caveats)
--keep bias: prefer the first-seen block order (default when bias is meaningful)
--ours <file> three-file merge: main's oplog at its tip, upstream, <file>
--result <file> three-file merge: write the merged oplog to <file> (default: --ours)
--schema <name> registered schema <name> (resolves via the chain when omitted)
--swap bias: prefer the second-seen block order
--theirs <file> three-file merge: your branch's oplog before this integration <file>
Refusals after a merge
After a git merge of two branches that each appended ops, the fork
is usually met by whichever command next reads the oplog, not by
reconcile. Each refusal prints a hint: line naming the next step;
this table collects them in one place. Each code’s exit status is on
Refusal codes.
| Refusal | Raised by | What it means | Recover with |
|---|---|---|---|
rule-prev-is-tail | op add, drift | An op’s prev= is not the op before it: a merge left a fork, or one tail op has a stale prev=. The refusal cannot tell which. | Just merged: retrofit reconcile. Otherwise retrofit op revise to fix the stale prev=. |
structural-gate, reporting schema-fork-unmerged | validate | The oplog holds an unmerged fork. | retrofit reconcile --schema <name> to inspect the fork, then a write mode. --allow-unmerged-fork reports without failing (exit 0). |
fork-in-range | migrate, snapshot, data list | The requested range crosses an unreconciled fork, so the schema at that cut is ambiguous. | retrofit reconcile <shared-prev>, as the hint prints it. The selector is the fork’s shared prev=, not a range. |
oplog-conflict-marker | every verb that reads the oplog | A merge that does not read .gitattributes (a host’s text merge, its web conflict editor, jj) left conflict markers in the oplog. | In the merge form, delete the marker lines, keep both sides’ operation lines, then retrofit reconcile. In the compact form, where a side revised or removed a line in the hunk, the three-file merge. |
oplog-two-fates | every verb that reads the oplog | Both sides revised one operation, or one revised and the other removed it, so the operation has two fates. | The edit the hint names, which leaves the operation one fate, then retrofit reconcile. |
fork-write-write | reconcile --clean with neither --keep nor --swap, and the three-file reconcile | Both orders replay, and the two sides set one property two ways. The refusal names what each flag leaves the property as, and the edit that undoes it. | The bias that keeps main’s operations first, then the edit the refusal names for it (Settle a property both sides set). |
fork-forced-order | reconcile --clean with no flag, or with the flag that names the other order, and the three-file reconcile | One order replays, or a Seal names the order, and the written order reports overrides nobody asked for. The refusal names the fork, why the order is forced and each override. | Re-run with the flag that names the forced order (--keep or --swap, as the refusal says). Exit 1. |
seal-over-fork | op seal | The unsealed tail contains a fork, and a Seal would attest an order no migration can emit. | retrofit reconcile, then seal the linear tail. |
write-over-fork | op remove, op revise (single, --batch, -i), op squash, op compact, op seal --compact, ops upgrade-sql-bodies, data witness, data repin (re-witnessing a witnessed record), data carry, schema ref-tables add/remove, schema form compact | The oplog holds a fork, which only reconcile may close, so the verb refuses before it writes or previews anything. | retrofit reconcile: --clean when an order replays, or --accept-dirty and then op revise when none does. |
fork-no-clean | reconcile --clean | Neither block order replays without a rule violation. | --accept-dirty to write the order anyway, then fix the tail with op revise. |
flag-not-applicable | reconcile --accept-dirty | The fork has a clean order, so there is nothing dirty to accept. | --clean. |
seal-forces-order | reconcile with --keep or --swap | Exactly one block has a Seal, so that block is written first and the bias flag has nothing to choose. | Drop the bias flag. To reorder anyway, remove the Seal with op unseal on the reconciled oplog. |
fork-concurrent-seals | reconcile with a write mode | Both blocks have a Seal. | --keep or --swap, plus --allow-sealed-rewrite=<opids> naming each Seal of the other block: those Seals are removed and its ops reopen. Left unnamed, the run refuses seal-removal-refused. Ship a hotfix ahead of the next release walks a sealed hotfix taken ahead of a sealed release. |
fork-straddles-seal | reconcile with a write mode | A Seal attests ops from both blocks, so no order preserves its digest. | Remove the spanning Seal with op unseal on a reconciled oplog, then re-run reconcile. |
fork-selector-unknown | reconcile <fork-selector> | The selector matches no fork’s shared prev=. | Bare retrofit reconcile lists each fork by its shared prev=. |
duplicate-opid, fork-duplicate-opid | validate; reconcile with a write mode | One opid sits on two lines, usually because a second rebase under the union driver kept both the old and the rewritten copy of a line. Neither command chooses between them. | Bare retrofit reconcile shows every copy; keep the one you mean and delete the others. |
structural-root-fork, fork-restart-roots | validate, op add, reconcile in every mode | The oplog holds two CreateSchema roots of one schema: one side restarted the log with import --force and the other appended to the old one. No order of the two histories is a merge, because the other side’s ops name element ids the restart replaced. --allow-unmerged-fork does not clear it. | Take the restarted side and add the other side’s ops again on it. |