retrofit
0.14.0
retrofit.sh

History checks

retrofit validate --history <dir> runs the history checks: it reads the commits a pull request’s integration made from a history bundle, a directory a CI job writes, and checks each commit’s oplog against what the oplog’s form promises. It runs no git, and it writes nothing. Check a pull request in CI is the task guide, and Gate merges on GitHub and GitLab sets the checks up on each host.

Synopsis

retrofit validate --history <dir> [--every-commit] [flags]

The bundle

MemberWhat it holds
version1, the member set this build reads
shallowtrue or false, as git rev-parse --is-shallow-repository prints it; true, or no member, refuses with history-bundle-refused
rolescandidate=<sha>, target=<sha> and, when the host gives one, before=<sha>, a line each
graphgit rev-list --parents from the roles: <sha> <parent>... per commit
messagesper commit its sha, a newline and its message, the records separated by a NUL byte
dead/<schema>the target’s tip, then every opid main’s history held in that schema’s oplog, one per line
commits/<sha>/<path>retrofit.toml and each oplog at that commit, at its path in the repository, with <path>.blob holding git’s blob id, or an empty <path>.absent where the commit has no such file
holders/<pr>/<path>optional: another open pull request’s oplog, at the path the candidate’s config records

The roles are the commits the host hands the job:

  • candidate: the commit the host tests, a pull request’s merge commit or a merge queue group’s commit.
  • target: the target branch’s tip.
  • before: the push’s previous tip, when the host gives one. An all-zero sha reads as none. Without it, the compact form’s compact-resurrection reports its check against the push’s previous tip unchecked, and the exit is unchanged.

Files a check needs

Which commits a check reads is validate’s choice, from the graph, the roles and the messages. A file a check needs and the bundle lacks refuses with history-bundle-missing: each file is named by its path in the bundle, on a history: missing line and in the record’s data.history.missing, and no check runs until none is missing. A commit’s retrofit.toml comes before the oplog it locates, so the first run names the config files and a later run names the oplogs.

A bundle it cannot trust

A bundle validate cannot trust refuses with history-bundle-refused before any check runs, naming the member: a shallow clone, a blob id that does not match its bytes, a parent outside the graph, a commit without its message, or a dead set that is absent or not derived through the target’s tip. The hint reads “write the bundle again from a full clone” and names the member to fix.

The dead set

The dead set is every opid main’s history held in a schema’s oplog, read from every commit reachable from the target’s tip, at the path the candidate’s config records. A dead set missing an opid lets resurrection, or the compact form’s compact-resurrection, pass an operation main had removed. A schema whose oplog moved has its earlier paths in the dead set too.

The checks

The candidate’s form line picks the checks, run per registered schema in the order of each table. Each check is listed with what fails it, as a failed check’s headline words it.

The merge form:

CheckFails when
own-historyan operation a commit of the pull request wrote is neither live nor traced in the candidate
revert-completenessa revert left an operation the reverted commit added live, or one it removed dead
grow-onlya merge commit holds no line of an operation live in one of its parents
resurrectionan operation an earlier commit removed or compacted is live again
fate-keptan operation’s fate is not the one an earlier commit’s file gave it
collapse-parenta commit drops an operation its parent held live, not traced
upstream-orderan operation main’s tip holds does not keep its place in the candidate, which puts the pull request’s operations after main’s last one
opaque-bodya body the pull request adds names no element, so a database apply checks its references and a rename or drop is not carried

The compact form:

CheckFails when
compact-resurrectionan operation removed or revised earlier is back in the result: a side removed or revised it, main’s history held it and its tip does not, or an earlier commit of the pull request held it and the push’s previous tip does not
compact-droppedan operation a side added is dropped from the result
compact-both-editedboth sides edited one operation and either wrote a new line on its element
revert-completenessas in the merge form
compact-held-elsewherenever: it is an advisory, reported when another open pull request still holds an operation this pull request removes or revises, and unchecked without holders/
upstream-orderas in the merge form
opaque-bodyas in the merge form

upstream-order reports a forced move, where a Seal decides the order or no order that keeps main’s operations first replays, as an advisory and passes. Its finding names main’s moved operations and the recourse in its recovery.

Status and exit

Each check reports passed, failed, unchecked (with a reason) or advisory. A failed check fails the run with the check’s name as its code, after every finding is reported; where several fail, the code is the first one’s. Its headline reads “history check own-history failed for schema sales: an operation a commit of the pull request wrote is neither live nor traced in the candidate (2 finding(s))”. An unchecked check and an advisory never fail the run.

With --allow-database-apply, opaque-body reports its findings as advisory and passes. The flag states that CI applies the range to a database before it lands, as Apply the migration to a scratch database does, and validate cannot check that. Without --history it refuses with flag-conflict.

Reverts

A revert pairs with the commit it reverts by the This reverts commit <sha> line git revert writes. A revert without it is reported unchecked, by name, and is never passed.

Every commit

By default only the candidate must validate. With --every-commit, every commit of the pull request in the bundle validates, each under its own form line. --every-commit without --history refuses with flag-conflict.

The record

--as json writes a validate-history record whose data.history holds:

  • checks: one entry per schema and check, with schema, check, status, reason on an unchecked one, and findings. Each finding has path, line, commit, message, the opid where it names one and a recovery where the check names one. An opaque-body finding adds the line’s operator, the body’s slot and, where one exists, the cause code naming why it names no element.
  • missing: the files history-bundle-missing names.

A run that fails ends with a failed record holding code, message, detail and hint. A refusal before any check runs names no file and line.

What each path promises

What each form promises:

  • The merge form. Every git path is clean, refused, or caught by validate and the history checks, except the paths below marked unsupported. The chief ones: regenerating a branch’s edits onto main’s file, which can leave a write-write that is no fork for reconcile to refuse; a pull request setting a property main also set after an earlier merge put main’s change before main’s last operations, which a host’s text merge keeps with no fork where the three-file step in CI does not run, or once the pull request has brought main in other than by the three-file merge; and a cherry-pick of one commit that brings an ancestor’s operation along.
  • The compact form. Union is sound for appends only. An edit of a committed line that another open branch holds is undone by that branch’s next merge, and keeping one side of an oplog conflict drops the other side’s operations. compact-resurrection and compact-dropped catch each where a history check runs over that integration.
  • The hosts. No host resolves an oplog conflict. Only GitLab honours merge=union, and Gerrit only where its server sets core.useGitattributesForMerge. On a host that merges as text, a clean merge touched no oplog hunk the other side touched, so it equals union in both forms, and a conflicting one is loud. On GitLab, the pipeline that tests what merges refuses a fork, which reaches main only on the setups GitLab setups marks unsupported.

Path by path, each outcome is one of four:

  • clean: the right result, with nothing to do;
  • refused: a loud stop, by git, the host or retrofit;
  • caught: loud, by validate, by a history check in CI, or by the three-file step in CI;
  • unsupported: silent, and listed here.
PathMerge formCompact form
A host’s merge button where both sides changed one oplog hunk (GitHub, Bitbucket Cloud, Gitea, Forgejo, Gerrit by default)refused: the host reports a conflictrefused
A host’s merge button where the sides changed different hunkscleanclean
A pull request setting a property main also set, after an earlier merge put main’s change before main’s last operations (a reconcile --clean merge of main, a forced move)caught: the three-file step in CI fails the pull request until it brings main in; refused by the three-file merge; unsupported through a host’s merge without the step, or after main is brought in other than by the three-file mergecaught: the three-file step in CI fails the pull request until it brings main in; refused by the three-file merge; unsupported through a host’s merge without the step, or after main is brought in other than by the three-file merge
A GitHub merge queuerefused: a conflicting entry leaves the queuerefused
GitLab’s merge, train or fast-forward, which honours unioncaught: the fork fails the pipeline that tests what mergesappends clean; an undone edit caught by compact-resurrection
A local git merge or git pullcaught: validate refuses the fork until reconcile closes itappends clean; an undone edit caught by compact-resurrection
A local git rebase or git pull --rebasecaught: a replayed commit may hold a fork, which reconcile closes at the tip; --every-commit checks eachappends clean; an undone edit caught by compact-resurrection
Keeping both sides of a conflict hunk (a web editor, an agent)clean, once reconcile closes the forkappends clean; an undone edit caught by compact-resurrection
Keeping one side of a conflict hunk (a web editor, --ours or --theirs, an agent)caught: grow-only when main’s lines go, own-history when the pull request’s own, resurrection and fate-kept when tracescaught: compact-dropped
Conflict markers left in the filerefused: every verb refuses oplog-conflict-markerrefused
jj or Sapling, which read no .gitattributesrefused: markers, which jj’s merge tool resolvesrefused: markers
A clone without .gitattributesrefused: a text conflictrefused
A git revert that union left incompletecaught: revert-completenesscaught: revert-completeness
A git merge -s ourscaught: grow-onlycaught: compact-dropped
A line deleted by handcaught: resurrectionan edit like any other
Stacked pull requests restacked after the parent squash-mergedcleanclean
A shallow CI checkoutrefused: history-bundle-refusedrefused
Regenerating the branch’s edits onto main’s fileunsupportedunsupported
A cherry-pick of one commit that brings an ancestor’s operation alongunsupportedunsupported
A rebase after a merge of main, with the replayed oplog closed by reconcile in the one file, not by the three-file mergeunsupported: the rebase drops the merge commit and the remedy the merge applied, and the one-file close does not bring it backunsupported
After a rebase, the three-file result amended into the last replayed commit, where an earlier merge of main kept one side of a conflict hunkunsupported: an operation that merge dropped is in no commit the pull request adds, so own-history reads nothingunsupported
Switching from the compact form to the merge form with branches openunsupporteddoes not apply
GitLab with automatic rebase, merged results without a train, or merge commits with branch pipelinesunsupported: a fork reaches mainunsupported

GitLab setups

The history check gates what merges only on a setup whose pipeline tests the commit that merges:

SetupThe pipeline testsA fork
A merge traineach car: main, the merge requests ahead of it, and its own; a car that passes moves main to the commit it testedrefused: the merge request leaves the train
Semi-linear or fast-forward merges, with “Pipelines must succeed” and automatic rebase offthe branch, which must be up to daterefused: GitLab’s rebase unions each commit, and the branch fails until the fork is closed
Semi-linear or fast-forward merges with automatic rebasenot the rebased resultmerges: unsupported
Merged results pipelines without a traina temporary merge, which main can move pastcan merge: unsupported
Merge commits, the default, with branch pipelinesthe branchmerges, and main’s own pipeline fails: unsupported

Diagnostics

Refusal codes gives the exit status of every code the history checks fail with, each check’s name included.

retrofit validate is the command’s --help, with its other flags and checks.

See also

Check a pull request in CI, Gate merges on GitHub and GitLab, Merge branches that change the oplog, The two forms, Output contract.

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

Published .