# The diff kit — show a unified diff: line numbers, changed words, folds, side by side

> `Osysharp.Diff` draws the text `git diff` prints — one file or many — as a reader expects to see it: each file under its path, old and new line numbers, removed and added lines on their tints with the changed words marked inside them, unchanged runs folded to a count (opened in place when you hand over the whole old and new text), in one column or side by side. Every line is plain text, the work is capped, and the kit declares no capability.

<!-- id: ui-diff-kit · area: ui · stability: preview · html: https://osysharp.com/reference/ui/diff-kit/ -->

## Summary        {#summary}
An app that keeps versions of something — a document, a config, a pipeline's output, a code change — sooner or later
has to show what changed between two of them. `Osysharp.Diff` takes the unified diff text and draws it; you do not
parse anything yourself.

```osy syntax
app Review {
  use Osysharp.Diff@1;
  use Osysharp.Ui;
  model "model/**/*.osy";
}
```

## Signature      {#signature}
```osy syntax
using Osysharp.Diff;

DiffView(string patch,                               // `git diff`, `git show`, `diff -u` — one file or many
         DiffLayout layout = DiffLayout.Unified,     // or DiffLayout.Split: old left, new right
         string oldText = "", string newText = "",   // the WHOLE old/new file — either makes every fold openable
         int maxLines = 1000,                        // the most lines of code drawn; the rest is counted
         int wordLimit = 500,                        // the longest line whose changed words are marked
         string label = "Diff")                      // what a screen reader and a test's `within:` call it

List<DiffFile> ParseDiff(string patch)               // the files: paths, change, hunks, lines, notes
DiffWordPair   DiffWords(string oldText, string newText, int maxChars)   // the changed words of one pair of lines
```

## Description    {#description}

### What it reads   {#reads}
The unified format, as git and `diff -u` print it: `diff --git` headers or bare `---`/`+++` pairs, `@@ -a,b +c,d @@`
hunks with their section text, `\ No newline at end of file`, new and deleted files, renames and copies (shown as
"renamed from …" and "copied from …"), mode changes, and binary files — a note, never their bytes. A commit message or an `index` line
around the files is passed over. A hunk ends when the line counts in its head are used up, so a removed line that
itself reads `-- comment` is a removed line, not the next file's header.

### What it draws   {#draws}
Each file under a bar with its path, what happened to it and `+added −removed`; each hunk under its `@@` line; every
line with its old and new number. A removed line paired with the added line after it has the words that changed marked
inside both. The unchanged lines before the first hunk and between two hunks fold to one row: "⋯ 3 unchanged lines".

### Opening a fold   {#folds}
A diff carries only a few lines of context, so a fold can only be a count — unless you give the view the whole file.
Pass `oldText` or `newText` (either; both is fine) and every fold becomes a button, "Show 3 unchanged lines", that draws
the lines in place with both numbers; the run after the last hunk is folded too. This is for a diff of ONE file: for a
diff of several, draw one `DiffView` per file with its own texts.

### Side by side   {#split}
`layout: DiffLayout.Split` sets the old file on the left and the new on the right. An unchanged line is on both sides;
a run of removed lines is set opposite the run of added lines after it, one for one, and the longer run's extra lines
face an empty cell.

### Hostile input   {#safety}
- **Every line is plain text.** A path, a hunk's section and a line are drawn as the characters they are —
  `<script>`, `**bold**`, `{name}` and `[Navigation](https://osysharp.com/reference/ui/navigation/)` included. Nothing in a diff is read as markup.
- **The work is bounded.** Parsing is one pass and never sizes anything from a hunk's head. Changed words are compared
  only for lines of at most `wordLimit` characters (default 500) and 200 words, and at most a million comparison
  cells per diff; a pair past either is drawn whole, and a note under the file says how many lines were not compared, and why: too long, or too many words.
- **The lines drawn are capped.** At most `maxLines` (default 1000); the rest is one row, "N more lines not shown, in
  M more files." Raise `maxLines` to draw more.
- **It declares no capability**: no egress, no secret, no native code, no script — the renderer's own elements only.

### Theming   {#theming}
Every colour, the face and the sizes are `Diff*` tokens that default to the app's own: `DiffSurface` is the surface,
`DiffInk` the text, `DiffGutterInk` the muted text, `DiffAddedMark`/`DiffRemovedMark` the success and danger ink. The
four line and word tints (`DiffAddedBg`, `DiffAddedWord`, `DiffRemovedBg`, `DiffRemovedWord`) are the kit's own quiet
greens and reds in light and dark. Shadow any of them in your theme ([theme tokens](https://osysharp.com/reference/ui/theming/)):

```osy syntax
theme Review {
  Colors { DiffAddedBg = Colors.SuccessTint; DiffRemovedBg = Colors.DangerTint; DiffFoldBg = Colors.Muted; }
  Font   { DiffFace = Font.Mono; }
}
```

| Token | Group | Default |
|---|---|---|
| `DiffSurface` · `DiffBorder` · `DiffInk` | Colors | `Surface` · `CardLine` · `OnSurface` |
| `DiffGutterInk` · `DiffNoteInk` | Colors | `TextMuted` |
| `DiffFileBg` · `DiffFileInk` | Colors | `Muted` · `OnSurface` |
| `DiffHunkBg` · `DiffHunkInk` · `DiffFoldBg` · `DiffFoldInk` · `DiffEmptyBg` | Colors | `Sunken` · `TextMuted` |
| `DiffAddedBg` · `DiffAddedWord` · `DiffRemovedBg` · `DiffRemovedWord` | Colors | the kit's light/dark tints |
| `DiffAddedMark` · `DiffRemovedMark` | Colors | `SuccessInk` · `DangerInk` |
| `DiffFace` | Font | `Mono` |
| `DiffText` · `DiffNote` | FontSize | `Label` · `Caption` |
| `DiffStrong` | FontWeight | `Semibold` |
| `DiffCard` | Radius | `Md` |

## Examples       {#examples}
```osy title="a change, with every fold openable" test app=ui-diff-kit
app Review {
  use Osysharp.Diff@1;
  use Osysharp.Ui;
  model "model/**/*.osy";
}

using Osysharp.Diff;

[Composable]
component ChangeOf(string patch, string before, string after) {
  render {
    DiffView(patch, oldText: before, newText: after, label: "Change");
  }
}
```

```osy title="the parser, as data" run app=ui-diff-kit
using Osysharp.Diff;

[Test]
void a_rename_and_its_changed_word_are_read() {
  var patch = "diff --git a/a.txt b/b.txt\nrename from a.txt\nrename to b.txt\n--- a/a.txt\n+++ b/b.txt\n@@ -1 +1 @@\n-price + tax\n+price + vat\n";
  var file = ParseDiff(patch)[0];
  Assert.Equal(DiffChange.Renamed, file.Change);
  Assert.Equal("b.txt", file.NewPath);
  Assert.Equal("vat", DiffWords("price + tax", "price + vat", 500).New.Single(s => s.Changed).Text);
}
```

## See also       {#see-also}
- [theme tokens](https://osysharp.com/reference/ui/theming/) — a theme's tokens, and shadowing a kit's
- [The chart kit — line, column, bar, scatter and candle, with no JavaScript](https://osysharp.com/reference/ui/chart-kit/) — the other pure-Osy# drawing kit, themed the same way
