YAML Diff

Compare two YAML documents and see what actually changed. The tool parses both sides, lists every added, removed, and modified key with its path, and shows a normalized line diff below. Whitespace, comments, and key order are ignored so you only see real changes.

How the YAML diff works

Both inputs are parsed into data structures. Syntax errors on either side are reported with the line number.
The two structures are walked together. Every leaf value that was added, removed, or changed is reported with its full path, such as server.timeouts.read or features[2].
Both sides are re-serialized with sorted keys and a fixed 2-space indent, and a unified line diff of that normalized text is displayed so you can see changes in context.

Why a structural diff beats a text diff

Running git diff on YAML often shows dozens of changed lines when someone reindented a block, reordered keys, or switched from flow to block style, even though nothing meaningful changed. A structural diff ignores all of that. It is the right tool when you want to answer "what will actually behave differently?" between two config files, two environments, or two versions of a Helm chart.

Example

Comparing these two files:

# original            # modified
app:                  app:
  version: "2.1.0"      name: yamlchecker
  name: yamlchecker     version: "2.2.0"
  debug: true           tls: true

reports:

~ app.version: "2.1.0" → "2.2.0"
- app.debug: true
+ app.tls: true

The swapped order of name and version is not reported because it does not change the data.

Frequently asked questions

Why does the diff say there are no differences when the files look different?

The comparison is structural. Key order, indentation, quoting style, comments, and flow versus block style do not change the data, so they are ignored. If the tool reports no differences, the two files will be parsed identically by any application.

How are lists compared?

Lists are compared by position. If you insert an item at the start of a list, every later item shifts and is reported as changed. This mirrors how most applications treat lists, where order matters.

Can I diff multi-document YAML?

Yes. Each side is parsed as a full stream. When either side has more than one document, the documents are compared as an ordered list.

Does this work for Kubernetes manifests and Helm output?

Yes, this is one of the most common uses. Paste the output of helm template or kubectl get -o yaml from two environments to see exactly which fields differ.

Related tools