retrofit
0.13.0
retrofit.sh

Versions and compatibility

This page says how a build is numbered, what may change between two releases, and which lines of the oplog and retrofit.toml decide whether a build reads a project.

Version numbers

VersionBuild
X.Y.Za release, such as 0.10.0
X.Y.Z-wip.Na WIP build toward the release X.Y.Z, such as 0.11.0-wip.33

Before 1.0 each release raises the minor and sets the patch to 0: the release after 0.10.0 is 0.11.0, and the WIP builds toward it are 0.11.0-wip.N. N counts WIP builds across every release and is never reset: 0.10.0-wip.31 was followed by 0.11.0-wip.32.

Releases and WIP builds

A release is published on GitHub as a release, and a WIP build as a pre-release.

  • The install script installs the latest release. Its --version flag installs a named release and --wip the newest WIP build; see Install script.
  • On Homebrew, the MonotonicHQ/tap/retrofit cask installs the latest release and the MonotonicHQ/tap/retrofit@wip cask the newest WIP build. The two casks conflict, so one is installed at a time; see Try a WIP.

Before 1.0

Before 1.0 no release promises compatibility with an earlier one. A release may change any command, flag, output shape, exit code, error or advisory code, or the oplog format.

The release notes list every such change. A change to the oplog’s operators, parameters, headers or seal bytes is listed under the release’s Log format heading, with what it means for an existing log: usually that the log is regenerated.

One build writes the same bytes for the same oplog on every machine and every run (Principles § 5). Two releases need not: the SQL snapshot and migrate emit for one oplog can differ between them.

What decides whether a build reads a project

The version number does not decide it. Four header lines open every oplog, and retrofit.toml names a schema_version:

# retrofit-oplog-format: 1
# retrofit-model-version: 1
# engine-version: 17
# retrofit-oplog-form: merge
LineWhat it namesThis build reads
# retrofit-oplog-format:the version of the oplog’s wire format1
# retrofit-model-version:the version of the operator catalog1
# engine-version:the PostgreSQL major the schema is pinned toa major PostgreSQL versions lists
# retrofit-oplog-form:the oplog’s form, merge or compactmerge or compact
schema_version in retrofit.tomlthe version of the config’s layout"1"

Before 1.0 a change to the log leaves both version numbers at 1 and is listed under Log format instead. A log an earlier build wrote can hold 1 and still fail: 0.10.0 added the # retrofit-oplog-form: line, and a log without it fails with oplog-form-header-missing.

When this build cannot read a line:

  • A newer oplog format. Every command that reads a log whose # retrofit-oplog-format: is above 1 fails with oplog-format-too-new. snapshot, migrate, identify and data list exit 2 with io-error, and import exits 1 with parse-error, each naming oplog-format-too-new in its message.
  • An older oplog format. A value below 1 fails with oplog-format-too-old, through the same codes. No command converts a log from one format to another. The Log format entry of the release that changed the format says what to do, usually regenerating the log.
  • A newer model version. A log whose # retrofit-model-version: is above 1 still parses, and op show prints it, but it cannot be written or rendered. op add, op revise, op seal and reconcile fail with model-version-too-new; snapshot, migrate and element list fail with render-blocked-on-unknowns; validate ends unverifiable (exit 2).
  • An unknown engine version. A major this build does not know fails with unknown-engine-version; see PostgreSQL versions.
  • A missing or unknown form. A log without a # retrofit-oplog-form: line fails with oplog-form-header-missing, and a value other than merge or compact with unknown-oplog-form.
  • A newer config. Every command that reads a retrofit.toml whose schema_version is above "1" fails with config-schema-too-new (exit 2). Any other value, or none, fails with config-invalid (exit 1).

Under the same numbers, a log a newer build wrote can hold an operator or a retrofit-* header key this build does not know. An unknown operator fails with unknown-operator, which snapshot, migrate, identify and data list name inside io-error. An unknown header key fails writes with writes-blocked-on-unknowns and renders with render-blocked-on-unknowns, and validate ends unverifiable. The output contract gives the exit status of each code.

What retrofit --version prints

retrofit --version
retrofit version 0.10.0 (65304cfdee81c33b78f400be435721c8bde3d9de, 2026-10-31T02:18:54Z)

The line names the build’s version, the full commit it was built from, and that commit’s date in UTC. A WIP build prints the same line with its X.Y.Z-wip.N version.

Before 1.0, any release may change behavior; the release notes list what changed.

Published .