YAML Diff Checker

Why YAML needs its own diff view

YAML is whitespace-significant, which means its most consequential changes are also its least visible ones. Moving a key two spaces to the left reparents it — a `resources` block that belonged to a container now belongs to the pod spec, and the manifest is either rejected or, worse, accepted with the limits silently dropped. In a plain text diff that change is a line whose leading whitespace differs. With YAML highlighting it is a key that has visibly changed nesting level relative to its neighbours, which is a thing you can actually see.

The same applies to the quieter YAML traps. An unquoted value that changed from `yes` to `true` is a no-op to the parser but looks like a change; an unquoted `NO` in a country-code field is the boolean `false` and looks like a country code; a version number written as `1.10` is a float that will serialize back as `1.1`. Highlighting separates the key from the value and the value from its quoting, so a change of quoting style — the thing that usually caused the surprise — stands out from a change of content.

This is otherwise the same comparison as the plain Text Diff: the two documents are aligned so matching lines fall away, added lines are marked on the right, removed lines on the left, and within a modified line the specific characters that differ are highlighted. Both panes stay editable, so you can fix the indentation on the spot and watch the difference resolve.

The YAML comparisons that come up in practice

Environment drift leads. Two copies of a Kubernetes manifest — staging and production, or last week's and this week's — where one works and one does not, and the answer is a replica count, an image tag, a resource limit or an environment variable. The same question in a `docker-compose.yml`, a Helm values file, or an Ansible playbook has the same shape and the same answer.

CI pipeline debugging is second. A GitHub Actions workflow that runs on one repository and fails on another, or a `.gitlab-ci.yml` that stopped working after a merge. Pipeline files accumulate small differences — a runner label, a cache key, a `needs` list, an `if` condition — and a diff finds them faster than reading two hundred lines of YAML twice. The same goes for comparing a workflow against the vendor's documented example.

Then there is upgrade review. A new version of a chart or an operator ships a new default values file, and you need to know what changed before you adopt it: which keys were added, which were renamed, which defaults moved. Diffing the old and new files answers that in a way the release notes usually do not. Comparing a rendered template against a live object serves the same purpose in the other direction — see what the cluster actually holds versus what you think you deployed.

One caveat worth internalizing: this is a textual comparison, so it reports differences in formatting as faithfully as differences in meaning. Two manifests that are semantically identical but written with different key ordering, different quoting, or anchors expanded in one and not the other will show up as different. When the question is 'is the resulting configuration the same?' rather than 'is the file the same?', convert both sides with YAML to JSON and compare the data instead — or run both through the YAML Formatter first to normalize the presentation, which resolves anchors and re-serializes at a consistent indent.

YAML differences that are not what they look like

A handful of YAML behaviours produce diffs that mislead on first reading. Knowing them saves the ten minutes you would otherwise spend chasing a change that is not there — or, worse, dismissing one that is.