onediffDocs
onediff docs
Everything about OneDiff 1.0.0: getting started, the text core (diff algorithms, patches, three-way merge), document comparison (the compare model, alignment, grouping, change semantics, combine and chains), HTML, PDF and scan output, migrating from DiffPlex and WmlComparer, and the measured results with the rows that lose.
Start
Getting startedInstall OneDiff 1.0.0 for .NET 10, diff and merge text, compare two documents into a verified change list, and write a redline as HTML, JSON or PDF. Pure C#, with no native code and no network access.OverviewWhat OneDiff is: a text diff core (diff, patches, three-way merge) and document comparison for PDFs and scans, the five 1.0.0 packages, the happy path, the low-level stages, and what comes in later releases.Samples and redline looksThe runnable code samples (one task per method) are in samples/OneDiff.Samples. This page covers the rendered files and the choice of form.Migrating from DiffPlexThis page maps the calls in DiffPlex's README, checked against the public members of DiffPlex 1.9.0, to the RecursiveAI.OneDiff calls that do the same job. It is a mapping only: OneDiff does not copy DiffPlex's types or shapes, and there is no compatibility layer. Where the…Migrating from WmlComparerThis page maps the calls in the README of Docxodus 15.0.0 (the NuGet package page; it is the maintained descendant of Open-Xml-PowerTools' WmlComparer, which that README says was removed in v11.0.0) to the OneDiff calls that do the same job. Names on the Docxodus side are…
Text core
Diff algorithmsBehaviour of MyersDiff, PatienceDiff and HistogramDiff. All three take two ReadOnlySpan of item ids (equal ids are equal items) and return a canonical EditScript: equal runs, and between them a deletion followed by an insertion.PatchesHow OneDiff reads, writes and applies unified diffs and diff-match-patch patch text. The code is in src/OneDiff/Patching; every rule below is checked by the gates in measurement.md.Three-way mergeThreeWayMerge (and Diff.Merge) merge a common ancestor (base) with two descendants (ours, theirs) over any sequence; the text form works on lines. The structure follows Khanna, Kuber and Pierce, "A Formal Investigation of Diff3" (FSTTCS 2007); the conflict layouts follow…Terminal and Markdown outputRenderers over a line-token TextDiff. Output is a pure function of the diff and the renderer's settings: the same input gives the same bytes on every platform. Every output line ends in \n, whatever the input's line endings.
Document comparison
The compare modelThis note describes the contracts of RecursiveAI.OneDiff.Documents: what a compared document is, how a comparison is built from five stages, and how every comparison is proved complete. Sources, alignment, in-pair diff, grouping, writers and models plug in through the types…AlignmentWhat Stages.Align does, in the order it does it, so that a different implementation (or a person correcting one) can follow the same rules. The result is an Alignment of Match, Move, Split and Merge links (see compare-model.md); verification checks it afterwards, so these…In-pair diff and groupingHow the edits inside a pair of aligned blocks are found, and how they become the changes a reader sees. Everything here is deterministic: the same inputs and settings give the same changes in the same order.Change semanticsWhat a change is about, and which changes belong together. Everything here is deterministic and works without a model. Nothing here alters an edit: cascades and renames are display groups over changes that stay in the list, types and values are labels on changes, and Verify…Combine and version chainsNormative description of Combination, ComparisonChain and ChangeReport in RecursiveAI.OneDiff.Documents (namespace OneDiff.Documents.Combine). The compare model, anchors, alignment and grouping they build on are in compare-model.md, alignment.md and grouping.md.HTML output and RedlineThis note describes what RecursiveAI.OneDiff.Documents writes as HTML, how a page maps back to the comparison it came from, and how adapter packages plug their inputs and output forms into Redline.Create and Comparison.SaveAs.
PDF and scans
PDF comparisonHow RecursiveAI.OneDiff.Pdf reads a digital PDF into the compare model, and how it marks a comparison on the original pages. Everything stated here is checked by the package's tests.Scans and imagesHow RecursiveAI.OneDiff.Ocr reads a scanned PDF or an image into the compare model, what the possible-OCR-error flag means, and how the scan gold set is built and scored.
Evidence
ResultsThe measured results of the 1.0 packages (RecursiveAI.OneDiff, .Documents, .Pdf, .Ocr and the onediff tool): the text core's exact gates, fuzzing and speed against the managed comparators; the PDF and scan engine's gates and gold-set scores; change semantics and combine…How it is measuredHow the exactness gates and the speed rows are reproduced. Everything here is tooling: it lives in tools/ and bench/, nothing in it ships in a package, and the comparators and reference tools it uses are only ever executed or called through their public interfaces.