retrofit
0.15.0-wip.89
retrofit.sh

These docs are for 0.15.0-wip.89, a WIP, and may describe what no release does yet. The newest release is 0.14.0: this page for 0.14.0.

retrofit validate

Validate retrofit.toml, project layout, and the oplog

Synopsis

Usage:
  retrofit validate [flags]

Options

Flags:
      --all                    report every registered schema, as with no --schema (and satisfying RETROFIT_REQUIRE_EXPLICIT_SCHEMA)
      --allow-database-apply   [apply context] with --history, attest that CI applies the range to a database before it lands: the opaque-body check lists its findings as advisory and does not fail
      --allow-unmerged-fork    report an unmerged fork as an advisory and exit 0; apply-risk hazards, seal-integrity refusals and standing violations still fail the run
      --every-commit           with --history, validate every commit of the PR in the bundle, not only the candidate
      --fail-on-apply-risk     fail (exit 2) on the apply-risk hazards in the migration window since the latest Seal (or the cut --from names): validating-fk, validating-check, add-not-null and a column-type change (a cast) that rewrites the table or scans it for an index or check, on a table that may hold rows; add-unique stays advisory, and so does a cast whose recovery retrofit does not vouch for
      --from string            with the apply-risk gate, judge the window (<cut>, head] in place of (latest Seal, head]; an anchor (root, last, seal, with ^ or ~N) or an opid prefix
  -h, --help                   help for validate
      --help-all               show extended help (vocabulary, semantics, caveats)
      --history string         check the history bundle at <dir> (written by the CI snippet; retrofit runs no git)
      --schema <name>          report only registered schema <name>'s findings; repeat it for each schema to report (every registered oplog is still read)

Global options

Global Flags:
      --as string        output mode: text | json (default "text")
  -C, --chdir string     treat <dir> as the working directory for the entire run
      --config string    retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
  -f, --file string      oplog file path; selects a registered [[schema]] path (overrides discovery)
      --no-consolidate   render every advisory occurrence instead of collapsing repeats
  -q, --quiet count      suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
  -v, --verbose          reveal info-tier advisories on stderr
Docs: https://docs.retrofit.sh/wip/commands/retrofit-validate/

retrofit validate --help-all adds:

Extended help:

What this verb checks:

  - retrofit.toml structure: unregistered-schema-in-directory-scope,
    directory-scope-duplicate-key, multiple-schemas-share-dir.
  - oplog placement and integrity: schema-stray-oplog,
    oplog-missing-at-recorded-path, oplog-unreadable,
    seal-digest-mismatch, sealed-oplog-unparsable.
  - oplog syntax: a line that does not parse fails the run wherever
    it falls, under the parser's code; merge conflict markers are
    named as such.
  - replay: the log is replayed against its op rules and its
    engine-version pin, and a rule violation fails the run. Syntax
    newer than this build's syntax level refuses syntax-not-available
    (exit 2) at any pin; an op the pin is too old for refuses
    unsupported-on-engine-version (exit 2). An unknown header or op
    key, or a newer retrofit-model-version, reports unverifiable
    (exit 2) when nothing else fails.
  - cross-schema references: a body that names an element no
    registered schema resolves fails the run under
    rule-exists-and-alive. The holders must be live at the tip.
  - forks: a fork is two or more ops sharing the same prev=, arising
    when concurrent branches each append onto the same op and a git
    merge concatenates both appends into one file. `validate` reports
    a fork as schema-fork-unmerged and, by default, fails the run
    (exit 2, code structural-gate) on an unmerged fork; pass
    --allow-unmerged-fork to report without failing. Either way,
    `validate` does not resolve a fork. Run
    `retrofit reconcile --help-all` for the block / bias / strictness
    vocabulary reconcile uses to close one.

Also prints a resolution preview: every (scope-dir, schema, source)
triple the config resolves to, so a directory-scope ambiguity is
visible before it surfaces as a load-time error elsewhere.

Scope: --schema <name>, repeatable, reports only the named schemas'
findings; no flag, or --all, reports every registered schema. With
several registered, the run opens by stating its scope. Every oplog is
still read, so an oplog that is missing, unreadable or unparsable, a
sealed range whose digest no longer matches, and a reference no schema
resolves fail the run whatever the scope. A --from opid names a place
in one schema's oplog, so pass --schema for that schema with it.

History mode: --history <dir> runs the history checks over a history
bundle, the files each check reads at each commit of a pull request,
which a CI job writes (retrofit runs no git). A file a check needs that
the bundle lacks refuses history-bundle-missing, naming each one, and
a bundle it cannot trust refuses history-bundle-refused before any
check runs. --every-commit validates every commit of the pull request,
not only the candidate. The CI guide on the docs site shows the script
that writes the bundle.

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

Published .