How yqr compares to other YAML tools

2 min read

How yqr compares

There are good YAML tools already. These pages are about where yqr differs from them, measured rather than asserted – every claim here comes from running both tools over the same file and diffing the result.

If a comparison here ever stops matching what you see, the other tool has probably improved and this page needs re-measuring. The versions used are named on each page so you can tell how stale it is.

  • yqr and yq – the closest neighbour, and the one most people arrive from.

Not everything in this space is a comparison. yqr edits; noyafmt formats. They are different jobs, and they share an engine – both are built on noyalib, so they agree about what your file means.

The difference is which bytes they are allowed to touch. Run both over the same file:

$ cat config.yaml
# Production cluster
defaults: &defaults
  mode:   0640      # octal, on purpose
  retries: 3
web:
  <<: *defaults
  name:   'web'

$ noyafmt config.yaml
# Production cluster
defaults: &defaults
  mode: 0640 # octal, on purpose
  retries: 3
web:
  <<: *defaults
  name: 'web'

noyafmt closed up the alignment padding, everywhere, on purpose – that is what a formatter is for. It kept the comment, the anchor, the merge key, the single quotes, and the octal 0640, because it works through the same lossless CST yqr reads.

$ yqr '.' config.yaml | diff - config.yaml && echo identical
identical
$ yqr '.defaults.retries = 5' config.yaml | diff config.yaml -
4c4
<   retries: 3
---
>   retries: 5

yqr changed one line, because one line is what the filter named. It has no opinion about the padding and never will – that is the guarantee, and a format subcommand would contradict it.

So reach for noyafmt when you want the file tidied, and yqr when you want one value changed and everything else left alone. They compose in a pipe, and noyafmt --check is the CI gate that exits 1 and names the files that need formatting.

Install both with cargo install noya-cli --locked, which also ships noyavalidate – a JSON Schema 2020-12 checker with autofix. That is a different question from yqr’s validate, which asks whether a file is correct YAML rather than whether it matches a schema.

Measured against noyafmt 0.0.27.