retrofit
0.13.0
retrofit.sh

retrofit validate

Validate retrofit.toml, project layout, and the oplog

Synopsis

Usage:
  retrofit validate [flags]

Options

Flags:
      --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 and add-not-null on a table that may hold rows; add-unique stays advisory
      --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)

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/current/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.

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 .