---
title: "Audit hidden whitespace differences in C#"
url: https://recursiveai.org/onediff/cookbook/audit-hidden-normalized-differences/
description: "Compare normalized text without losing the whitespace differences: inspect OneDiff’s hidden-change ledger and reconstruct each original string."
version: "1.0.1"
---

# Audit hidden whitespace differences in C#

**OneDiff** is a free, open-source diff library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneDiff.Documents) · [GitHub](https://github.com/recursive-ai-oss/onediff-csharp) · [Docs](https://recursiveai.org/onediff/docs/) · [Download example (.zip)](https://recursiveai.org/onediff/cookbook/audit-hidden-normalized-differences/audit-hidden-normalized-differences.zip)

Hide whitespace edits while keeping a ledger, a categorized record of the differences.

For real files, follow the [PDF-loading example](https://recursiveai.org/onediff/docs/getting-started/#redline-pdfs); export Word documents to PDF first.

```shell
dotnet add package RecursiveAI.OneDiff.Documents
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
using OneDiff.Documents;
using OneDiff.Documents.Model;

var settings = new CompareSettings {
    Hidden = CategorySet.Of(
        LedgerCategory.Whitespace)
};
var result = Comparison.Of(
    Doc("Pay  now."), Doc("Pay now."), settings);
Console.WriteLine(
    $"Hidden: {result.Ledger.TotalCount}");

static CompareDocument Doc(string raw)
{
    var builder =
        new CompareDocumentBuilder();
    builder.Add(NodeKind.Paragraph,
        NodeContent.FromNormalized(
        TextNormalization.Normalize(raw,
            [TypographicNormalizer.Instance])));
    return builder.Build();
}
```

```text
Hidden: 1
```

Unzip [the example](https://recursiveai.org/onediff/cookbook/audit-hidden-normalized-differences/audit-hidden-normalized-differences.zip), then `dotnet run`.

## Full program

```csharp
using OneDiff.Documents;
using OneDiff.Documents.Model;

var oldBuilder = new CompareDocumentBuilder();
var newBuilder = new CompareDocumentBuilder();
oldBuilder.Add(NodeKind.Paragraph, Content("Pay  now."));
newBuilder.Add(NodeKind.Paragraph, Content("Pay now."));
var oldDocument = oldBuilder.Build();
var newDocument = newBuilder.Build();
var settings = new CompareSettings
{
    Hidden = CategorySet.Of(LedgerCategory.Whitespace),
    ThrowOnFailure = true
};
var result = Comparison.Of(oldDocument, newDocument, settings);
Console.WriteLine($"Visible changes: {result.Changes.Length}");
foreach (var entry in result.Ledger.Entries)
{
    Console.WriteLine($"Hidden {entry.Category}: {entry.Count}");
    foreach (var location in entry.Locations)
        Console.WriteLine($"  nodes {location.OldNode} -> {location.NewNode}");
}
Console.WriteLine($"Old raw: [{oldDocument.Nodes[0].RawText}]");
Console.WriteLine($"New raw: [{newDocument.Nodes[0].RawText}]");
Console.WriteLine($"Verified: {result.Verification.Passed}");

static NodeContent Content(string raw) => NodeContent.FromNormalized(
    TextNormalization.Normalize(raw, [TypographicNormalizer.Instance]),
    Anchor.ForNode("paragraph-0"));
```

`dotnet run` prints:

```text
Visible changes: 0
Hidden Whitespace: 1
  nodes 0 -> 0
Old raw: [Pay  now.]
New raw: [Pay now.]
Verified: True
```

The full program preserves both raw strings and prints each ledger entry’s category, count and node locations. If strict verification fails, it throws `ComparisonVerificationException` instead of falling back.

## Variations

After the full program’s comparison, show whitespace instead of hiding it:

```csharp
var visible = Comparison.Of(oldDocument, newDocument,
    settings with { Hidden = CategorySet.None });
Console.WriteLine($"Visible: {visible.Changes.Length}; hidden: {visible.Ledger.TotalCount}");
```

```text
Visible: 1; hidden: 0
```

## Related recipes

[Verify document diff completeness](https://recursiveai.org/onediff/cookbook/verify-document-comparison-completeness/)

<!-- article -->

## The short answer

To ignore whitespace without losing the record of what changed, keep two things: normalized text for comparison and normalization folds—records of the original characters replaced during normalization—for reconstruction. OneDiff’s `TypographicNormalizer` produces both. Put them together in a node with `NodeContent.FromNormalized`, then hide `LedgerCategory.Whitespace` in the comparison settings. Inspect `Changes` for visible edits and `Ledger` for hidden differences. An empty changes array alone is not an equality test.

The example compares two synthetic paragraphs, not files: `Pay  now.` has two spaces and `Pay now.` has one. Both normalize to the same comparison text. The ledger still records the hidden whitespace difference, and `RawText` returns each original string. No source-file adapter or external service is involved.

## Can diff ignore whitespace?

Yes, but choose what “ignore” means. In this example it means hiding a difference from the visible changes while retaining a categorized record of it. It does not mean deleting whitespace from both inputs before building the document model.

The built-in typographic normalizer folds runs of horizontal whitespace, quotes and the dash family. The settings decide which categories stay folded during comparison. A fold in a category that is not hidden is undone, so the underlying difference can appear as ordinary text. Hiding whitespace alone therefore does not also hide every typographic difference. The variation above turns all hiding off and shows the space edit as a visible change.

Retain the folds when constructing nodes. Copying only `normalized.Text` into a new node throws away the information needed to reconstruct its raw text. `FromNormalized` copies the normalized text and folds together.

## How to compare if two files are the same?

First decide whether you mean identical bytes, identical extracted content, or equivalent content under chosen settings. This recipe answers the last question for compare models. It does not establish byte equality of source files, and it does not read document formats on its own.

Within the model, review both the changes and ledger. A hidden difference is still a difference. For an audit trail, retain the settings alongside the result so a reviewer can see which categories were hidden. `LedgerEntry` supplies a category, count and locations; each location names the old and new nodes and carries their anchors. The full program uses a named paragraph anchor so the location can be traced back to this synthetic input.

The ledger covers hidden differences outside regions already shown by a change. Differences inside a shown region belong to that change, not a second ledger entry. Do not interpret the ledger count as a count of all changed characters or add it to a visible change count as though those units were interchangeable.

## Can diff ignore whitespace and newlines?

Whitespace normalization and layout line breaks are separate categories. `TypographicNormalizer` handles horizontal whitespace; PDF sources can supply `LineBreaks` folds for layout artifacts. Merely hiding `LineBreaks` does not create those folds in a hand-built model. A source must preserve the original text and describe the normalization it actually performed.

For this reason, do not use the whitespace example as an instruction to remove every newline. A paragraph boundary may be meaningful structure rather than a layout artifact. Keep the model faithful to the input, then choose the projection the reviewer needs. The engine recomputes the hidden-difference ledger during verification, so an omitted ledger entry is a verification failure rather than silently accepted output.
