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
| Member | What it holds |
|---|---|
version | 1, the member set this build reads |
shallow | true or false, as git rev-parse --is-shallow-repository prints it; true, or no member, refuses with history-bundle-refused |
roles | candidate=<sha>, target=<sha> and, when the host gives one, before=<sha>, a line each |
graph | git rev-list --parents from the roles: <sha> <parent>... per commit |
messages | per 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’scompact-resurrectionreports its check against the push’s previous tipunchecked, 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:
| Check | Fails when |
|---|---|
own-history | an operation a commit of the pull request wrote is neither live nor traced in the candidate |
revert-completeness | a revert left an operation the reverted commit added live, or one it removed dead |
grow-only | a merge commit holds no line of an operation live in one of its parents |
resurrection | an operation an earlier commit removed or compacted is live again |
fate-kept | an operation’s fate is not the one an earlier commit’s file gave it |
collapse-parent | a commit drops an operation its parent held live, not traced |
upstream-order | an 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-body | a 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:
| Check | Fails when |
|---|---|
compact-resurrection | an 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-dropped | an operation a side added is dropped from the result |
compact-both-edited | both sides edited one operation and either wrote a new line on its element |
revert-completeness | as in the merge form |
compact-held-elsewhere | never: 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-order | as in the merge form |
opaque-body | as 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, withschema,check,status,reasonon an unchecked one, andfindings. Each finding haspath,line,commit,message, theopidwhere it names one and arecoverywhere the check names one. Anopaque-bodyfinding adds the line’soperator, the body’sslotand, where one exists, thecausecode naming why it names no element.missing: the fileshistory-bundle-missingnames.
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
validateand 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 forreconcileto 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-resurrectionandcompact-droppedcatch 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 setscore.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.
| Path | Merge form | Compact 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 conflict | refused |
| A host’s merge button where the sides changed different hunks | clean | clean |
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 merge | 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 merge |
| A GitHub merge queue | refused: a conflicting entry leaves the queue | refused |
| GitLab’s merge, train or fast-forward, which honours union | caught: the fork fails the pipeline that tests what merges | appends clean; an undone edit caught by compact-resurrection |
A local git merge or git pull | caught: validate refuses the fork until reconcile closes it | appends clean; an undone edit caught by compact-resurrection |
A local git rebase or git pull --rebase | caught: a replayed commit may hold a fork, which reconcile closes at the tip; --every-commit checks each | appends 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 fork | appends 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 traces | caught: compact-dropped |
| Conflict markers left in the file | refused: every verb refuses oplog-conflict-marker | refused |
jj or Sapling, which read no .gitattributes | refused: markers, which jj’s merge tool resolves | refused: markers |
A clone without .gitattributes | refused: a text conflict | refused |
A git revert that union left incomplete | caught: revert-completeness | caught: revert-completeness |
A git merge -s ours | caught: grow-only | caught: compact-dropped |
| A line deleted by hand | caught: resurrection | an edit like any other |
| Stacked pull requests restacked after the parent squash-merged | clean | clean |
| A shallow CI checkout | refused: history-bundle-refused | refused |
| Regenerating the branch’s edits onto main’s file | unsupported | unsupported |
| A cherry-pick of one commit that brings an ancestor’s operation along | unsupported | unsupported |
A rebase after a merge of main, with the replayed oplog closed by reconcile in the one file, not by the three-file merge | unsupported: the rebase drops the merge commit and the remedy the merge applied, and the one-file close does not bring it back | unsupported |
| 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 hunk | unsupported: an operation that merge dropped is in no commit the pull request adds, so own-history reads nothing | unsupported |
| Switching from the compact form to the merge form with branches open | unsupported | does not apply |
| GitLab with automatic rebase, merged results without a train, or merge commits with branch pipelines | unsupported: a fork reaches main | unsupported |
GitLab setups
The history check gates what merges only on a setup whose pipeline tests the commit that merges:
| Setup | The pipeline tests | A fork |
|---|---|---|
| A merge train | each car: main, the merge requests ahead of it, and its own; a car that passes moves main to the commit it tested | refused: the merge request leaves the train |
| Semi-linear or fast-forward merges, with “Pipelines must succeed” and automatic rebase off | the branch, which must be up to date | refused: GitLab’s rebase unions each commit, and the branch fails until the fork is closed |
| Semi-linear or fast-forward merges with automatic rebase | not the rebased result | merges: unsupported |
| Merged results pipelines without a train | a temporary merge, which main can move past | can merge: unsupported |
| Merge commits, the default, with branch pipelines | the branch | merges, 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.