Upgrading from V2

New features and breaking changes

New Features

• Keeps yaml comments and formatting, can specify yaml tags when updating.

• Handles anchors!

• Can print out matching paths and values when splatting, more info here.

• JSON output works for all commands! Yaml files with multiple documents are printed out as one JSON document per line, more info here

• Deep splat (**) to match arbitrary paths and match nodes by their children, more info here

Breaking Changes

Parsing values from the CLI

In V3 users are able to better control how values are treated when updating YAML by using a new --tag argument (see more info here). A result of this however, is that quoting values, e.g. "true" will no longer have an effect on how the value is interpreted like it did in V2.

For instance, to get the string "true" into a yaml file:

V2:

yq n a.path '"true"'

V3

yq n a.path --tag '!!str' true

Reading paths that don't exist

In V2 this would return null, V3 does not return anything.

Similarly, reading null yaml values null, ~ and , V2 returns null whereas V3 returns the values as is.

This is a result of taking effort not to format values coming in and out of the original YAML.

Update scripts file format has changed to be more powerful.

Comments can be added, and delete commands have been introduced.

V2

b.e[+].name: Mike Farah

V3

- command: update 
  path: b.e[+].thing
  value:
    #great 
    things: frog # wow!
- command: delete
  path: b.d

Reading and splatting, matching results are printed once per line.

e.g:

parent:
  childA: 
    no: matches here
  childB:
    there: matches
    hi: no match
    there2: also matches

yq r sample.yaml 'parent.*.there*'

V2

- null
- - matches
  - also matches

V3

matches
also matches

Converting JSON to YAML

As JSON is a subset of YAML, and yq now preserves the formatting of the passed in document, you will most likely need to use the --prettyPrint flag to format the JSON document as idiomatic YAML. See Working with JSON for more info.