Tips, Tricks, Troubleshooting

Validating yaml files
Yaml files can be surprisingly lenient in what can be parsed as a yaml file. A reasonable way of validation a yaml file is to ensure the top level is a map or array (although it is valid yaml to have scalars at the top level, but often this is not what you want). This can be done by:
1
yq e --exit-status 'tag == "!!map" or tag== "!!seq"' file.txt > /dev/null
Copied!
Split expressions over multiple lines to improve readability
Feel free to use multiple lines in your expression to improve readability.
Use with if you need to make several updates to the same path.
1
yq eval --inplace '
2
  with(.a.deeply.nested; 
3
    . = "newValue" | . style="single") |
4
  with(.b.another.nested; 
5
    . = "cool" | . style="folded")
6
' my_file.yaml
Copied!
Create bash array
Given a yaml file like
1
coolActions:
2
  - create
3
  - edit
4
  - delete
Copied!
You can create a bash array named actions by:
1
> readarray actions < <(yq e '.coolActions[]' sample.yaml)
2
> echo "${actions[1]}"
3
edit
Copied!
Set contents from another file
Use an environment variable with the strenv operator to inject the contents from an environment variable.
1
LICENSE=$(cat LICENSE) yq eval -n '.a = strenv(LICENSE)'
Copied!
Note that bash substitution "$(..)" trims newlines, this will cause string blocks to start with |- instead of |. If you want to keep your nice trailing newline, read more here​
Special characters in strings
The strenv operator is a great way to handle special characters in strings:
1
VAL='.a |[email protected]  == "string2"' yq e '.a = strenv(VAL)' example.yaml
Copied!
Quotes in Windows Powershell
Powershell has its own way of handling quotes:
1
PS > yq e -n '.test = ""something""'
2
test: something
3
PS >
Copied!
See https://github.com/mikefarah/yq/issues/747 for more trickery.
Merge / combine all documents into one
To merge all given yaml files into one, use the reduce operator with the * (multiply) operator. Note the use of ea or eval-all to load all files into memory so that they can be merged.
1
yq ea '. as $item ireduce ({}; . * $item )' file1.yml file2.yml ...
Copied!
Merge an array of objects by key
See here for a working example.
Creating a new file / working with blank documents
To create a new yaml file simply:
1
yq e -n '.someNew="content"' > newfile.yml
Copied!
Comparing yaml files
The best way to run a diff is to use yq to normalise the yaml files and then just use diff. Here is a simple example of using pretty print -P to normalise the styling and running diff:
1
diff <(yq e -P 'sort_keys(..)' file1.yaml) <(yq e -P 'sort_keys(..)' file2.yaml)
Copied!
This way you can use the full power of diff and normalise the yaml files as you like.
You may also want to remove all comments using ... comments=""
Reading multiple streams (STDINs)
Like diff and other bash commands, you can use <(exp) to pipe in multiple streams of data into yq. instance:
1
yq e '.apple' <(curl -s https://somewhere/data1.yaml) <(cat file.yml)
Copied!
Updating deeply selected paths
or why is yq only returning the updated yaml
The most important thing to remember to do is to have brackets around the LHS expression - otherwise what yq will do is first filter by the selection, and then, separately, update the filtered result and return that subset.
1
yq '(.foo.bar[] | select(name == "fred) | .apple) = "cool"'
Copied!
Combining multiple files into one
In order to combine multiple yaml files into a single file (with --- separators) you can just:
1
yq e '.' somewhere/*.yaml
Copied!
Multiple updates to the same path
You can use the with operator to set a nested context:
1
yq eval 'with(.a.deeply ; .nested = "newValue" | .other= "newThing")' sample.yml
Copied!
The first argument expression sets the root context, and the second expression runs against that root context.
yq adds a !!merge tag automatically
The merge functionality from yaml v1.1 (e.g. <<:has actually been removed in the 1.2 spec. Thankfully, yq underlying yaml parser still supports that tag - and it's extra nice in that it explicitly puts the !!merge tag on key of the map entry. This tag tells other yaml parsers that this entry is a merge entry, as opposed to a regular string key that happens to have a value of <<:. This is backwards compatible with the 1.1 spec of yaml, it's simply an explicit way of specifying the type (for instance, you can use a !!str tag to enforce a particular value to be a string.
Although this does affect the readability of the yaml to humans, it still works and processes fine with various yaml processors.