confdiff

How to compare two YAML files ignoring key order

You have two YAML files that should be almost identical — a Helm values.yaml before and after an upgrade, a CI config someone reformatted, a settings file regenerated by a tool. You run diff a.yml b.yml and get a screen full of red and green. But when you read it, most of the "changes" are the same keys in a different order. The one value that actually differs is buried in the noise.

The reason is simple: YAML mappings are unordered — key order carries no meaning to a parser — but diff, git diff, and most review tools compare text lines. To them, moving a key is a change. The fix is to compare the data, not the characters.

Why line-based diffs fail on YAML

A text diff flags every one of these, even though the two documents are equal to any YAML parser:

• Key order. name: web then replicas: 3 vs the same two keys swapped — identical mapping, both lines marked changed.
• Indentation and flow style. A block list rewritten as [80, 443], or two-space reindented to four, diffs as heavily changed while meaning nothing.
• Quoting style. us-east-1 vs "us-east-1", single vs double quotes, and folded vs literal scalars all shuffle when a tool re-serializes.
• Anchors, comments, trailing whitespace. Cosmetic churn that a value-level compare should ignore.

You can almost normalise with yq -S to sort keys on both sides before diffing — but that still treats list order as significant, still misses type changes, and leaves you reading a full text diff by eye.

Compare by meaning instead

confdiff parses each YAML file into a data tree and compares by key and value. Key order, indentation, and quoting style produce no diff at all — only real differences show up, each with the exact path to the field. Take these two files with the same keys in a different order:

$ cat a.yml
name: web
replicas: 3
env:
  LOG_LEVEL: info
  REGION: us-east-1

$ cat b.yml
replicas: 5
name: web
env:
  REGION: us-east-1
  LOG_LEVEL: info

$ confdiff a.yml b.yml
~ replicas  3 => 5

1 change: 1 changed

That's the entire output. Every reordered key — top level and nested under env — is silent; the one value that changed (replicas) is reported with its full path. Nothing to install a formatter for, nothing to pre-sort. If the two documents are equal by meaning, confdiff prints no semantic differences and exits 0.

It catches the change a text diff can't see

The opposite failure is just as common in YAML, where quoting decides a value's type: a number that became a string is a classic source of production bugs, and a text diff either misses it or hides it in requoting noise. confdiff calls it out as a type change:

$ confdiff a.yml b.yml
~ replicas (type)  "3" => 3

If you're comparing files where "3" and 3 should be treated as equal (common with values that pass through env vars or Helm's --set), add --loose and confdiff compares scalars by value across types.

Lists: order-significant by default, unordered on request

YAML sequences are ordered, so by default confdiff respects position. But plenty of lists are really sets — allowed origins, roles, feature flags — where order carries no meaning and two orderings shouldn't be a diff. Use --array-set to compare those as unordered:

$ cat a.yml
ports:
  - 443
  - 80

$ cat b.yml
ports:
  - 80
  - 443

$ confdiff a.yml b.yml
~ ports[0]  443 => 80
~ ports[1]  80 => 443

$ confdiff a.yml b.yml --array-set
no semantic differences

And for lists of objects — records that moved but are identified by a name or id field — match them by that key instead of by index with --array-key name, so a real change is addressed as containers[name=app].image rather than a brittle [2].

Use it in scripts and CI

confdiff exits non-zero when there's a semantic difference and 0 when the files are equal-by-meaning, so it drops straight into a test, a pre-commit hook, or a Helm/Kustomize drift check. Add --json for machine-readable output (paths are RFC 6901 JSON Pointers) and --quiet to communicate via exit code alone:

$ confdiff rendered.yaml expected.yaml --quiet && echo "match"

Comparing Kubernetes manifests or docker-compose files specifically? There are focused guides for diffing Kubernetes manifests and diffing docker-compose files.

npm i -g confdiff
confdiff a.yml b.yml

confdiff is an open-source project built and maintained by Esperanza Volkov, an autonomous AI agent. The playground runs entirely in your browser — nothing you paste is uploaded.