Migrating from DiffPlex

This 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 README does not say exactly what a DiffPlex option does, the row says "closest" and you should check the result on your own data. Rows marked not provided have no equivalent in the text core.

Everything below is in namespace OneDiff (and OneDiff.Tokenization, OneDiff.Merge where noted). All calls are static and take plain strings.

The result: DiffResult → TextDiff and EditScript

Diff.Lines, Diff.Words, Diff.Characters, Diff.Graphemes and Diff.Text return a TextDiff: both strings, their tokens and an EditScript. The script is a list of Edit runs (Equal, Delete, Insert) whose indices count tokens of the old and new text. TextDiff.OldSpan(edit) and NewSpan(edit) give a run's text back. Replacements are a Delete followed by an Insert.

Differ (IDiffer)

Which algorithm runs is a parameter: Diff.Lines(old, new, DiffAlgorithm.Patience) (Myers, Patience, Histogram). To cap the work on untrusted text: Diff.Lines(old, new, new DiffSettings { MaxWork = 100_000 }).Diagnostic.CostCapReached. DiffPlex's Differ has no algorithm choice or cap to map these to.

Chunkers (IChunker)

Tokenizer.Tokenize(text, kind) returns the token ranges if you want to look at them.

InlineDiffBuilder (the README's console sample)

OneDiff's line type is DiffRun, not DiffPiece, so a file can import both DiffPlex.DiffBuilder.Model and OneDiff while you migrate it without an ambiguous reference.

The README builds an inline model with InlineDiffBuilder.Diff(before, after) and prints each line of diff.Lines with a +, - or blank prefix according to line.Type. TextDiff.Lines is the same view: one entry per line with its kind, text (without the line break) and line number in each text.

var sb = new StringBuilder();
foreach (DiffRun line in Diff.Lines(before, after).Lines)
{
    string prefix = line.Kind switch { EditKind.Insert => "+ ", EditKind.Delete => "- ", _ => "  " };
    sb.Append(prefix).Append(line.Text).Append('\n');
}

TextDiff.Pieces gives the same runs without cutting them at line breaks (for a word diff, runs of words). diff.Script, OldSpan and NewSpan are still there when you want token indices. For a finished rendering instead of a loop: Diff.ToTerminal(diff) (ANSI colours, changed words highlighted, context lines and hunks), Diff.ToMarkdown(diff) (a fenced diff block) and Diff.ToMarkdownInline(Diff.Words(a, b)) (<del>/<ins> inline).

SideBySideDiffBuilder (ISideBySideDiffBuilder)

Diff.SideBySide(old, new) returns a SideBySideDiff: aligned Rows, each with a Kind (Unchanged, Deleted, Inserted, Modified) and a Left and Right cell. A cell has the line number, the text and Parts, which for a modified line are the word-level pieces (Equal and Delete on the left, Equal and Insert on the right), the way DiffPlex fills SubPieces.

foreach (SideBySideRow row in Diff.SideBySide(before, after).Rows)
{
    string left = row.Left?.Text ?? "", right = row.Right?.Text ?? "";
    Console.WriteLine($"{row.Kind,-9} | {left,-30} | {right}");
}

With an already computed line diff (for example one made with a comparer): Diff.ToSideBySide(diff).

UnidiffRenderer

Diff.Unified has no timestamps in the header lines, and also takes algorithm: or, to cap the work, DiffSettings. Unified text parses back with UnifiedPatch.Parse and applies with Diff.ApplyUnified.

ThreeWayDiffer (IThreeWayDiffer)

DiffPlex's CreateMerge(baseText, oldText, newText, ignoreWhiteSpace, ignoreCase, chunker) takes the two modified versions as "old text" and "new text"; they map to ours and theirs, in that order. Its result, ThreeWayMergeResult, has IsSuccessful, MergedPieces, ConflictBlocks and DiffResult.

TextMerge merge = Diff.Merge(baseText, ours: oldText, theirs: newText);
if (merge.HasConflicts)
    foreach (MergeConflict c in merge.Conflicts)
        Console.WriteLine($"conflict at ours line {c.OursLine}: {c.OursText} / {c.TheirsText}");
else Console.WriteLine(merge.Text);

Changes on adjacent lines are a conflict, as in git; changes separated by an unchanged line merge cleanly.

Beyond DiffPlex

The text core also has semantic and efficiency cleanup (Diff.Semantic, Diff.Efficient), diff-match-patch patch text (Diff.PatchText, Diff.ApplyPatchText) and unified patch apply with fuzz (Diff.ApplyUnified), and the onediff diff | patch | merge command line over the same calls. Document comparison lives in RecursiveAI.OneDiff.Documents and the adapter packages.

The snippets and mappings above that show behaviour are covered by tests in the repository (MigrationPageTests).