Line diff vs structural diff
A YAML file is two things at once: a stream of text and a parsed tree. Two diffs answer two different questions.
- Line diff answers what did the bytes change? It is what code review tools and Git show. It picks up trailing whitespace, comment edits, indentation tweaks, and key reordering - including changes that have no effect on the parsed value.
- Structural diff answers what did the data change? It parses both sides into a tree, walks them together, and reports added, removed, and changed values by dotted path. Two YAML files that produce the same tree are reported as semantically equal.
For pull-request review and audit trails, line diff is what you want - it preserves the human-authored structure. For deciding whether a change is safe to apply, structural diff is what you want - it filters out noise and shows only the consequential edits.
Common YAML diff use cases
- Kubernetes drift detection - compare a live manifest dumped with
kubectl get -o yamlagainst the version in Git to spot out-of-band edits. - Helm chart upgrades - diff a rendered chart between two versions before running
helm upgradein production. - Docker Compose review - structural diff makes anchor-heavy compose files reviewable; line diff alone is often unreadable.
- Config rollouts - confirm that a refactor (key sort, comment cleanup, anchor extraction) is semantically a no-op before merging.
- CI artifacts - validate that a generated config matches a checked-in baseline.
FAQs
What does the YAML diff tool do?
It compares two YAML files and shows what changed. The line view highlights added, removed, and unchanged lines like git diff. The structural view parses both files and reports semantic changes by dotted key path - so a key reorder shows as no change, while a renamed key shows as one removed plus one added.
How is structural diff different from line diff?
Line diff compares the raw text. If you reorder two top-level keys, the line diff shows one removed and one added even though the parsed value is identical. Structural diff parses both sides into trees and walks them, so reordering, comment changes, and indentation tweaks register as no change. Use line diff for review, structural diff for correctness.
Does the YAML diff tool detect semantic equality?
Yes. When both inputs parse, the tool reports 'semantically equal' if the resulting trees are deep-equal - meaning the YAML files would behave identically when consumed by any parser, regardless of key order, comment placement, or whitespace differences.
Can I diff invalid YAML?
The line-level diff works on any input, including syntactically invalid YAML. The structural diff requires both sides to parse successfully; if either side has a syntax error, the structural pane shows the error with a line and column number and disables structural comparison until the input is fixed.
Is the YAML diff tool sent to a server?
No. Parsing and diffing run entirely in your browser, so your YAML files never leave your device. The tool is safe for secrets, internal infrastructure config, and proprietary data.
How do I diff two YAML files online?
Paste the original file into the left pane, the new version into the right pane, and the tool compares them automatically. Use the Upload buttons to load .yaml or .yml files. Toggle between line view and structural view; both update live as you edit.
Does the diff tool follow YAML anchors and aliases?
Yes. Both files are parsed with a YAML 1.2 library that resolves anchors and merge keys before the structural diff runs. Two files that produce the same expanded value are reported as semantically equal even if one uses anchors and the other inlines the values.
What is the maximum file size for YAML diff?
5 MB per side. Larger files should be diffed locally with git diff or a CLI tool like dyff (https://github.com/homeport/dyff) which is built specifically for YAML and Kubernetes manifests.
Can I compare multi-document YAML files?
Yes. The line diff works on any input, multi-document or otherwise. The structural diff currently parses the first document of each side; for multi-document comparisons (e.g. Kubernetes manifests bundling many resources), split the files into per-document chunks before diffing.
How does YAML diff handle key order?
Structural diff treats two YAML maps with the same keys and values as identical regardless of order, because YAML maps are unordered by spec. Line diff respects order because it operates on raw text. If you care about deterministic ordering, run both files through the YAML formatter with sort keys enabled before diffing.
Why does my YAML diff show changes I did not make?
Three common causes: trailing-whitespace differences (line diff catches them, structural diff ignores them), CRLF vs LF line endings, or a YAML parser that auto-resolves aliases differently between the two sides. Format both files with the same indentation and key order before diffing to eliminate noise.
Can I share a diff URL?
Yes. The Share buttons on each pane copy a link that encodes that pane's content. Send the link to a teammate to load the same comparison in their browser. For diffs you want to keep, copy the structured change list and paste it into a pull-request description.