suyiiyii/yq
1
0
Fork 0
mirror of https://github.com/mikefarah/yq.git synced 2024-12-19 20:19:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

GitBook: [#206] deep update example

Browse Source
This commit is contained in:
Mike Farah 2021-10-30 03:14:39 +00:00 committed by gitbook-bot
parent b723783231
commit fbe266a166
No known key found for this signature in database
GPG Key ID: 07D2180C7B12D0FF
49 changed files with 7156 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
.gitbook/assets/test.zip Normal file
View File

Binary file not shown.

183
README.md
View File

@ -0,0 +1,183 @@
---
description: yq is a lightweight and portable command-line YAML processor
---
# yq
 ![Build](https://github.com/mikefarah/yq/workflows/Build/badge.svg) ![Docker Pulls](https://img.shields.io/docker/pulls/mikefarah/yq.svg) ![Github Releases (by Release)](https://img.shields.io/github/downloads/mikefarah/yq/total.svg) ![Go Report](https://goreportcard.com/badge/github.com/mikefarah/yq)
`yq` is a lightweight and portable command-line YAML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json. It doesn't yet support everything `jq` does - but it does support the most common operations and functions, and more is being added continuously.
`yq` is written in go - so you can download a dependency free binary for your platform and you are good to go! If you prefer there are a variety of package managers that can be used as well as docker, all listed below.
## v3 users:
Version 4 of `yq` is a major upgrade that now fully supports complex expressions for powerful filtering, slicing and dicing yaml documents. This new version uses syntax very similar to `jq` and works very similarly, so if you've used `jq` before this should be a low learning curve - however it is _quite_ different from previous versions of `yq`. Take a look at the [upgrade guide](upgrading-from-v3.md) for help.
Support for v3 will cease August 2021, until then, critical bug and security fixes will still get applied if required.
## How it works
`yq` works by running`yaml` nodes against a filter expression. The filter expression is made of of operators that pipe into each other. yaml nodes are piped through operators, operators may either return a different set of nodes (e.g. children) or modify the nodes (e.g. update values). See the [operator documentation](https://mikefarah.gitbook.io/yq/operators) for more details and examples.
```
yq eval 'select(.a == "frog") | .b.c = "dragon"' file.yaml
```
## Install
#### [Download the latest binary](https://github.com/mikefarah/yq/releases/latest)
### wget
Use wget to download the pre-compiled binaries:
#### Compressed via tar.gz
```bash
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY}.tar.gz -O - |\
tar xz && mv ${BINARY} /usr/bin/yq
```
#### Plain binary
```bash
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY} -O /usr/bin/yq &&\
chmod +x /usr/bin/yq
```
For instance, VERSION=v4.2.0 and BINARY=yq\_linux\_amd64
### Homebrew
[Homebrew](https://brew.sh) is a package manger for MacOS and Linux.
```
brew install yq
```
for the (deprecated) v3 version
```
brew install yq@3
```
Note that for v3, as it is a versioned brew it will not add the `yq` command to your path automatically. Please follow the instructions given by brew upon installation.
### Snap
Snap can be used on all major Linux distributions.
```
snap install yq
```
or, for the (deprecated) v3 version:
```
snap install yq --channel=v3/stable
```
**Snap notes**
`yq` installs with [_strict confinement_](https://docs.snapcraft.io/snap-confinement/6233) in snap, this means it doesn't have direct access to root files. To read root files you can:
```
sudo cat /etc/myfile | yq e '.a.path' -
```
And to write to a root file you can either use [sponge](https://linux.die.net/man/1/sponge):
```
sudo cat /etc/myfile | yq e '.a.path = "value"' - | sudo sponge /etc/myfile
```
or write to a temporary file:
```
sudo cat /etc/myfile | yq e '.a.path = "value"' | sudo tee /etc/myfile.tmp
sudo mv /etc/myfile.tmp /etc/myfile
rm /etc/myfile.tmp
```
### Docker
**Oneshot use:**
```bash
docker run --rm -v "${PWD}":/workdir mikefarah/yq <command> [flags] [expression ]FILE...
```
**Run commands interactively:**
```bash
docker run --rm -it -v "${PWD}":/workdir --entrypoint sh mikefarah/yq
```
It can be useful to have a bash function to avoid typing the whole docker command:
```bash
yq() {
docker run --rm -i -v "${PWD}":/workdir mikefarah/yq "$@"
}
```
### Go Get
```
GO111MODULE=on go get github.com/mikefarah/yq
```
## Community Supported Installation methods
As these are supported by the community :heart: - however, they may be out of date with the officially supported releases.
## Webi
```
webi yq
```
See [webi](https://webinstall.dev) for more infor.
Supported by @adithyasunil26 ([https://github.com/webinstall/webi-installers/tree/master/yq](https://github.com/webinstall/webi-installers/tree/master/yq))
### Chocolatey for Windows:
```
choco install yq
```
Supported by @chillum ([https://chocolatey.org/packages/yq](https://chocolatey.org/packages/yq))
### MacPorts:
```
sudo port selfupdate
sudo port install yq
```
Supported by @herbygillot ([https://ports.macports.org/maintainer/github/herbygillot](https://ports.macports.org/maintainer/github/herbygillot))
### Alpine Linux
* Enable edge/community repo by adding `$MIRROR/alpine/edge/community` to `/etc/apk/repositories`
* Update database index with `apk update`
* Install yq with `apk add yq`
Supported by Tuan Hoang [https://pkgs.alpinelinux.org/package/edge/community/x86/yq](https://pkgs.alpinelinux.org/package/edge/community/x86/yq)
#### On Ubuntu 16.04 or higher from Debian package:
```bash
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys CC86BB64
sudo add-apt-repository ppa:rmescandon/yq
sudo apt update
sudo apt install yq -y
```
Supported by @rmescandon ([https://launchpad.net/\~rmescandon/+archive/ubuntu/yq](https://launchpad.net/\~rmescandon/+archive/ubuntu/yq))
## Parsing engine and YAML spec support
Under the hood, yq uses [go-yaml v3](https://github.com/go-yaml/yaml/tree/v3) as the yaml parser, which supports [yaml spec 1.2](https://yaml.org/spec/1.2/spec.html). In particular, note that in 1.2 the values 'yes'/'no' are no longer interpreted as booleans, but as strings.

62
SUMMARY.md Normal file
View File

@ -0,0 +1,62 @@
# Table of contents
* [yq](README.md)
* [Upgrading from V3](upgrading-from-v3.md)
## Commands
* [Evaluate](commands/evaluate.md)
* [Evaluate All](commands/evaluate-all.md)
* [Shell Completion](commands/shell-completion.md)
***
* [Operators](operators/README.md)
* [Add](operators/add.md)
* [Alternative (Default value)](operators/alternative-default-value.md)
* [Anchor and Alias Operators](operators/anchor-and-alias-operators.md)
* [Assign (Update)](operators/assign-update.md)
* [Boolean Operators](operators/boolean-operators.md)
* [Collect into Array](operators/collect-into-array.md)
* [Comment Operators](operators/comment-operators.md)
* [Contains](operators/contains.md)
* [Create, Collect into Object](operators/create-collect-into-object.md)
* [Delete](operators/delete.md)
* [Document Index](operators/document-index.md)
* [Entries](operators/entries.md)
* [Env Variable Operators](operators/env-variable-operators.md)
* [Equals](operators/equals.md)
* [File Operators](operators/file-operators.md)
* [Has](operators/has.md)
* [Keys](operators/keys.md)
* [Length](operators/length.md)
* [Multiply (Merge)](operators/multiply-merge.md)
* [Path](operators/path.md)
* [Pipe](operators/pipe.md)
* [Recursive Descent (Glob)](operators/recursive-descent-glob.md)
* [Reduce](operators/reduce.md)
* [Select](operators/select.md)
* [Sort Keys](operators/sort-keys.md)
* [Split into Documents](operators/split-into-documents.md)
* [String Operators](operators/string-operators.md)
* [Style](operators/style.md)
* [Subtract](operators/subtract.md)
* [Tag](operators/tag.md)
* [Traverse (Read)](operators/traverse-read.md)
* [Union](operators/union.md)
* [Unique](operators/unique.md)
* [Variable Operators](operators/variable-operators.md)
* [With](operators/with.md)
## Usage
* [Output format](usage/output-format.md)
* [Working with Properties](usage/properties.md)
* [Working with JSON](usage/convert.md)
* [Front Matter](usage/front-matter.md)
* [GitHub Action](usage/github-action.md)
* [Tips, Tricks, Troubleshooting](usage/tips-and-tricks.md)
***
* [Github Page](https://github.com/mikefarah/yq)

45
commands/evaluate-all.md Normal file
View File

@ -0,0 +1,45 @@
---
description: >-
Read all documents of all given yaml files into memory, then run the given
expression once against the lot.
---
# Evaluate All
Evaluate All is most useful when needing to run expressions that depend on multiple yaml documents or files. Merge is probably the most common reason why evaluate all would be used. Note that `eval-all` consumes more memory than `evaluate`.
Like `evaluate` you can use `-` to pipe from STDIN.
## Usage
```bash
yq eval-all [expression] [yaml_file1]... [flags]
```
Aliases: `eval-all, ea`
## Examples
```bash
# merges f2.yml into f1.yml (inplace)
yq eval-all --inplace 'select(fileIndex == 0) * select(fileIndex == 1)' f1.yml f2.yml
# you can merge into a file, piping from STDIN
cat somefile.yml | yq eval-all --inplace 'select(fileIndex == 0) * select(fileIndex == 1)' f1.yml -
```
## Flags
```bash
-h, --help help for eval-all
-C, --colors force print with colors
-e, --exit-status set exit status if there are no matches or null or false is returned
-I, --indent int sets indent level for output (default 2)
-i, --inplace update the yaml file inplace of first yaml file given.
-M, --no-colors force print with no colors
-N, --no-doc Don't print document separators (---)
-n, --null-input Don't read input, simply evaluate the expression given. Useful for creating yaml docs from scratch.
-j, --tojson output as json. Set indent to 0 to print json in one line.
-v, --verbose verbose mode
```

54
commands/evaluate.md Normal file
View File

@ -0,0 +1,54 @@
---
description: >-
Evaluates the given expression against each yaml document in each file, in
sequence
---
# Evaluate
## Usage:&#x20;
```bash
yq eval [expression] [yaml_file1]... [flags]
```
Aliases: `eval, e`
Note that you can pass in `-` as a filename to pipe from STDIN.
## Examples:
```bash
# runs the expression against each file, in series
yq e '.a.b | length' f1.yml f2.yml
# '-' will pipe from STDIN
cat file.yml | yq e '.a.b' f1.yml - f2.yml
# prints out the file
yq e sample.yaml
cat sample.yml | yq e
# prints a new yaml document
yq e -n '.a.b.c = "cat"'
# updates file.yaml directly
yq e '.a.b = "cool"' -i file.yaml
```
## Flags:
```
-h, --help help for eval
-C, --colors force print with colors
-e, --exit-status set exit status if there are no matches or null or false is returned
-I, --indent int sets indent level for output (default 2)
-i, --inplace update the yaml file inplace of first yaml file given.
-M, --no-colors force print with no colors
-N, --no-doc Don't print document separators (---)
-n, --null-input Don't read input, simply evaluate the expression given. Useful for creating yaml docs from scratch.
-j, --tojson output as json. Set indent to 0 to print json in one line.
-v, --verbose verbose mode
```

69
commands/shell-completion.md Normal file
View File

@ -0,0 +1,69 @@
---
description: >-
Generate a shell completion file for supported shells
(bash/fish/zsh/powershell)
---
# Shell Completion
```bash
yq shell-completion --variation=zsh
```
Prints to StdOut a shell completion script for zsh shell.
### Bash (default)
```bash
source <(yq shell-completion bash)
```
#### To load completions for each session, execute once:
Linux:
```bash
yq shell-completion bash > /etc/bash_completion.d/yq
```
MacOS:
```bash
yq shell-completion bash > /usr/local/etc/bash_completion.d/yq
```
### zsh
If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:
```bash
echo "autoload -U compinit; compinit" >> ~/.zshrc
```
#### To load completions for each session, execute once:
```bash
yq shell-completion zsh > "${fpath[1]}/_yq"
```
You will need to start a new shell for this setup to take effect.
### fish
```bash
yq shell-completion fish | source
```
#### To load completions for each session, execute once:
```
yq shell-completion fish > ~/.config/fish/completions/yq.fish
```
### PowerShell
```bash
yq shell-completion powershell
```
Users need PowerShell version 5.0 or above, which comes with Windows 10 and can be downloaded separately for Windows 7 or 8.1. They can then write the completions to a file and source this file from their PowerShell profile, which is referenced by the $Profile environment variable.

118
operators/README.md Normal file
View File

@ -0,0 +1,118 @@
# Operators
## Operators
In `yq` expressions are made up of operators and pipes. A context of nodes is passed through the expression and each operation takes the context as input and returns a new context as output. That output is piped in as input for the next operation in the expression. To begin with, the context is set to the first yaml document of the first yaml file (if processing in sequence using eval).
Lets look at a couple of examples.
### Example with a simple operator
Given a document like:
```yaml
- [a]
- "cat"
```
with an expression:
```
.[] | length
```
`yq` will initially set the context as single node of the entire yaml document, an array of two elements.
```yaml
- [a]
- "cat"
```
This gets piped into the splat operator `.[]` which will split out the context into a collection of two nodes `[a]` and `"cat"`. Note that this is _not_ a yaml array.
The `length` operator take no arguments, and will simply return the length of _each_ matching node in the context. So for the context of `[a]` and `"cat"`, it will return a new context of `1` and `3`.
This being the last operation in the expression, the results will be printed out:
```
1
3
```
## Example with an operator that takes arguments.
Given a document like:
```yaml
a: cat
b: dog
```
with an expression:
```
.a = .b
```
The `=` operator takes two arguments, a `lhs` expression, which in this case is `.a` and `rhs` expression which is `.b`.
It pipes the current, lets call it 'root' context through the `lhs` expression of `.a` to return the node
```yaml
cat
```
Note that this node holds not only its value 'cat', but comments and metadata too, including path and parent information.
The `=` operator then pipes the 'root' context through the `rhs` expression of `.b` to return the node
```yaml
dog
```
Both sides have now been evaluated, so now the operator copies across the value from the RHS to the value on the LHS, and it returns the now updated context:
```yaml
a: dog
b: dog
```
## Relative update (e.g. `|=`)
There is another form of the `=` operator which we call the relative form. It's very similar to `=` but with one key difference when evaluating the RHS expression.
In the plain form, we pass in the 'root' level context to the RHS expression. In relative form, we pass in _each result of the LHS_ to the RHS expression. Let's go through an example.
Given a document like:
```yaml
a: 1
b: thing
```
with an expression:
```
.a |= . + 1
```
Similar to the `=` operator, `|=` takes two operands, the LHS and RHS.
It pipes the current context (the whole document) through the LHS expression of `.a` to get the node value:
```
1
```
Now it pipes _that LHS context_ into the RHS expression `. + 1` (whereas in the `=` plain form it piped the original document context into the RHS) to yield:
```
2
```
The assignment operator then copies across the value from the RHS to the value on the LHS, and it returns the now updated 'root' context:
```yaml
a: 2
b: thing
```

343
operators/add.md Normal file
View File

@ -0,0 +1,343 @@
# Add
Add behaves differently according to the type of the LHS:
* arrays: concatenate
* number scalars: arithmetic addition
* string scalars: concatenate
Use `+=` as append assign for things like increment. Note that `.a += .x` is equivalent to running `.a = .a + .x`.
## Concatenate and assign arrays
Given a sample.yml file of:
```yaml
a:
val: thing
b:
- cat
- dog
```
then
```bash
yq eval '.a.b += ["cow"]' sample.yml
```
will output
```yaml
a:
val: thing
b:
- cat
- dog
- cow
```
## Concatenate arrays
Given a sample.yml file of:
```yaml
a:
- 1
- 2
b:
- 3
- 4
```
then
```bash
yq eval '.a + .b' sample.yml
```
will output
```yaml
- 1
- 2
- 3
- 4
```
## Concatenate null to array
Given a sample.yml file of:
```yaml
a:
- 1
- 2
```
then
```bash
yq eval '.a + null' sample.yml
```
will output
```yaml
- 1
- 2
```
## Add new object to array
Given a sample.yml file of:
```yaml
a:
- dog: woof
```
then
```bash
yq eval '.a + {"cat": "meow"}' sample.yml
```
will output
```yaml
- dog: woof
- cat: meow
```
## Add string to array
Given a sample.yml file of:
```yaml
a:
- 1
- 2
```
then
```bash
yq eval '.a + "hello"' sample.yml
```
will output
```yaml
- 1
- 2
- hello
```
## Append to array
Given a sample.yml file of:
```yaml
a:
- 1
- 2
b:
- 3
- 4
```
then
```bash
yq eval '.a = .a + .b' sample.yml
```
will output
```yaml
a:
- 1
- 2
- 3
- 4
b:
- 3
- 4
```
## Append another array using +=
Given a sample.yml file of:
```yaml
a:
- 1
- 2
b:
- 3
- 4
```
then
```bash
yq eval '.a += .b' sample.yml
```
will output
```yaml
a:
- 1
- 2
- 3
- 4
b:
- 3
- 4
```
## Relative append
Given a sample.yml file of:
```yaml
a:
a1:
b:
- cat
a2:
b:
- dog
a3: {}
```
then
```bash
yq eval '.a[].b += ["mouse"]' sample.yml
```
will output
```yaml
a:
a1:
b:
- cat
- mouse
a2:
b:
- dog
- mouse
a3: {b: [mouse]}
```
## String concatenation
Given a sample.yml file of:
```yaml
a: cat
b: meow
```
then
```bash
yq eval '.a = .a + .b' sample.yml
```
will output
```yaml
a: catmeow
b: meow
```
## Number addition - float
If the lhs or rhs are floats then the expression will be calculated with floats.
Given a sample.yml file of:
```yaml
a: 3
b: 4.9
```
then
```bash
yq eval '.a = .a + .b' sample.yml
```
will output
```yaml
a: 7.9
b: 4.9
```
## Number addition - int
If both the lhs and rhs are ints then the expression will be calculated with ints.
Given a sample.yml file of:
```yaml
a: 3
b: 4
```
then
```bash
yq eval '.a = .a + .b' sample.yml
```
will output
```yaml
a: 7
b: 4
```
## Increment numbers
Given a sample.yml file of:
```yaml
a: 3
b: 5
```
then
```bash
yq eval '.[] += 1' sample.yml
```
will output
```yaml
a: 4
b: 6
```
## Add to null
Adding to null simply returns the rhs
Running
```bash
yq eval --null-input 'null + "cat"'
```
will output
```yaml
cat
```

104
operators/alternative-default-value.md Normal file
View File

@ -0,0 +1,104 @@
# Alternative (Default value)
This operator is used to provide alternative (or default) values when a particular expression is either null or false.
## LHS is defined
Given a sample.yml file of:
```yaml
a: bridge
```
then
```bash
yq eval '.a // "hello"' sample.yml
```
will output
```yaml
bridge
```
## LHS is not defined
Given a sample.yml file of:
```yaml
{}
```
then
```bash
yq eval '.a // "hello"' sample.yml
```
will output
```yaml
hello
```
## LHS is null
Given a sample.yml file of:
```yaml
a: ~
```
then
```bash
yq eval '.a // "hello"' sample.yml
```
will output
```yaml
hello
```
## LHS is false
Given a sample.yml file of:
```yaml
a: false
```
then
```bash
yq eval '.a // "hello"' sample.yml
```
will output
```yaml
hello
```
## RHS is an expression
Given a sample.yml file of:
```yaml
a: false
b: cat
```
then
```bash
yq eval '.a // .b' sample.yml
```
will output
```yaml
cat
```

421
operators/anchor-and-alias-operators.md Normal file
View File

@ -0,0 +1,421 @@
# Anchor and Alias Operators
Use the `alias` and `anchor` operators to read and write yaml aliases and anchors. The `explode` operator normalises a yaml file (dereference (or expands) aliases and remove anchor names).
`yq` supports merge aliases (like `<<: *blah`) however this is no longer in the standard yaml spec (1.2) and so `yq` will automatically add the `!!merge` tag to these nodes as it is effectively a custom tag.
## Merge one map
see [https://yaml.org/type/merge.html](https://yaml.org/type/merge.html)
Given a sample.yml file of:
```yaml
- &CENTER
x: 1
y: 2
- &LEFT
x: 0
y: 2
- &BIG
r: 10
- &SMALL
r: 1
- !!merge <<: *CENTER
r: 10
```
then
```bash
yq eval '.[4] | explode(.)' sample.yml
```
will output
```yaml
x: 1
y: 2
r: 10
```
## Merge multiple maps
see [https://yaml.org/type/merge.html](https://yaml.org/type/merge.html)
Given a sample.yml file of:
```yaml
- &CENTER
x: 1
y: 2
- &LEFT
x: 0
y: 2
- &BIG
r: 10
- &SMALL
r: 1
- !!merge <<:
- *CENTER
- *BIG
```
then
```bash
yq eval '.[4] | explode(.)' sample.yml
```
will output
```yaml
r: 10
x: 1
y: 2
```
## Override
see [https://yaml.org/type/merge.html](https://yaml.org/type/merge.html)
Given a sample.yml file of:
```yaml
- &CENTER
x: 1
y: 2
- &LEFT
x: 0
y: 2
- &BIG
r: 10
- &SMALL
r: 1
- !!merge <<:
- *BIG
- *LEFT
- *SMALL
x: 1
```
then
```bash
yq eval '.[4] | explode(.)' sample.yml
```
will output
```yaml
r: 10
x: 1
y: 2
```
## Get anchor
Given a sample.yml file of:
```yaml
a: &billyBob cat
```
then
```bash
yq eval '.a | anchor' sample.yml
```
will output
```yaml
billyBob
```
## Set anchor
Given a sample.yml file of:
```yaml
a: cat
```
then
```bash
yq eval '.a anchor = "foobar"' sample.yml
```
will output
```yaml
a: &foobar cat
```
## Set anchor relatively using assign-update
Given a sample.yml file of:
```yaml
a:
b: cat
```
then
```bash
yq eval '.a anchor |= .b' sample.yml
```
will output
```yaml
a: &cat
b: cat
```
## Get alias
Given a sample.yml file of:
```yaml
b: &billyBob meow
a: *billyBob
```
then
```bash
yq eval '.a | alias' sample.yml
```
will output
```yaml
billyBob
```
## Set alias
Given a sample.yml file of:
```yaml
b: &meow purr
a: cat
```
then
```bash
yq eval '.a alias = "meow"' sample.yml
```
will output
```yaml
b: &meow purr
a: *meow
```
## Set alias to blank does nothing
Given a sample.yml file of:
```yaml
b: &meow purr
a: cat
```
then
```bash
yq eval '.a alias = ""' sample.yml
```
will output
```yaml
b: &meow purr
a: cat
```
## Set alias relatively using assign-update
Given a sample.yml file of:
```yaml
b: &meow purr
a:
f: meow
```
then
```bash
yq eval '.a alias |= .f' sample.yml
```
will output
```yaml
b: &meow purr
a: *meow
```
## Explode alias and anchor
Given a sample.yml file of:
```yaml
f:
a: &a cat
b: *a
```
then
```bash
yq eval 'explode(.f)' sample.yml
```
will output
```yaml
f:
a: cat
b: cat
```
## Explode with no aliases or anchors
Given a sample.yml file of:
```yaml
a: mike
```
then
```bash
yq eval 'explode(.a)' sample.yml
```
will output
```yaml
a: mike
```
## Explode with alias keys
Given a sample.yml file of:
```yaml
f:
a: &a cat
*a: b
```
then
```bash
yq eval 'explode(.f)' sample.yml
```
will output
```yaml
f:
a: cat
cat: b
```
## Explode with merge anchors
Given a sample.yml file of:
```yaml
foo: &foo
a: foo_a
thing: foo_thing
c: foo_c
bar: &bar
b: bar_b
thing: bar_thing
c: bar_c
foobarList:
b: foobarList_b
!!merge <<:
- *foo
- *bar
c: foobarList_c
foobar:
c: foobar_c
!!merge <<: *foo
thing: foobar_thing
```
then
```bash
yq eval 'explode(.)' sample.yml
```
will output
```yaml
foo:
a: foo_a
thing: foo_thing
c: foo_c
bar:
b: bar_b
thing: bar_thing
c: bar_c
foobarList:
b: bar_b
thing: foo_thing
c: foobarList_c
a: foo_a
foobar:
c: foo_c
a: foo_a
thing: foobar_thing
```
## Dereference and update a field
\`Use explode with multiply to dereference an object
Given a sample.yml file of:
```yaml
item_value: &item_value
value: true
thingOne:
name: item_1
!!merge <<: *item_value
thingTwo:
name: item_2
!!merge <<: *item_value
```
then
```bash
yq eval '.thingOne |= explode(.) * {"value": false}' sample.yml
```
will output
```yaml
item_value: &item_value
value: true
thingOne:
name: item_1
value: false
thingTwo:
name: item_2
!!merge <<: *item_value
```

274
operators/assign-update.md Normal file
View File

@ -0,0 +1,274 @@
# Assign (Update)
## Create yaml file
Running
```bash
yq eval --null-input '.a.b = "cat" | .x = "frog"'
```
will output
```yaml
a:
b: cat
x: frog
```
## Update node to be the child value
Given a sample.yml file of:
```yaml
a:
b:
g: foof
```
then
```bash
yq eval '.a |= .b' sample.yml
```
will output
```yaml
a:
g: foof
```
## Double elements in an array
Given a sample.yml file of:
```yaml
- 1
- 2
- 3
```
then
```bash
yq eval '.[] |= . * 2' sample.yml
```
will output
```yaml
- 2
- 4
- 6
```
## Update node from another file
Note this will also work when the second file is a scalar (string/number)
Given a sample.yml file of:
```yaml
a: apples
```
And another sample another.yml file of:
```yaml
b: bob
```
then
```bash
yq eval-all 'select(fileIndex==0).a = select(fileIndex==1) | select(fileIndex==0)' sample.yml another.yml
```
will output
```yaml
a:
b: bob
```
## Update node to be the sibling value
Given a sample.yml file of:
```yaml
a:
b: child
b: sibling
```
then
```bash
yq eval '.a = .b' sample.yml
```
will output
```yaml
a: sibling
b: sibling
```
## Updated multiple paths
Given a sample.yml file of:
```yaml
a: fieldA
b: fieldB
c: fieldC
```
then
```bash
yq eval '(.a, .c) = "potatoe"' sample.yml
```
will output
```yaml
a: potatoe
b: fieldB
c: potatoe
```
## Update string value
Given a sample.yml file of:
```yaml
a:
b: apple
```
then
```bash
yq eval '.a.b = "frog"' sample.yml
```
will output
```yaml
a:
b: frog
```
## Update string value via |=
Note there is no difference between `=` and `|=` when the RHS is a scalar
Given a sample.yml file of:
```yaml
a:
b: apple
```
then
```bash
yq eval '.a.b |= "frog"' sample.yml
```
will output
```yaml
a:
b: frog
```
## Update selected results
Given a sample.yml file of:
```yaml
a:
b: apple
c: cactus
```
then
```bash
yq eval '(.a[] | select(. == "apple")) = "frog"' sample.yml
```
will output
```yaml
a:
b: frog
c: cactus
```
## Update array values
Given a sample.yml file of:
```yaml
- candy
- apple
- sandy
```
then
```bash
yq eval '(.[] | select(. == "*andy")) = "bogs"' sample.yml
```
will output
```yaml
- bogs
- apple
- bogs
```
## Update empty object
Given a sample.yml file of:
```yaml
{}
```
then
```bash
yq eval '.a.b |= "bogs"' sample.yml
```
will output
```yaml
{a: {b: bogs}}
```
## Update empty object and array
Given a sample.yml file of:
```yaml
{}
```
then
```bash
yq eval '.a.b.[0] |= "bogs"' sample.yml
```
will output
```yaml
{a: {b: [bogs]}}
```

299
operators/boolean-operators.md Normal file
View File

@ -0,0 +1,299 @@
# Boolean Operators
The `or` and `and` operators take two parameters and return a boolean result.
`not` flips a boolean from true to false, or vice versa.
`any` will return `true` if there are any `true` values in a array sequence, and `all` will return true if _all_ elements in an array are true.
`any_c(condition)` and `all_c(condition)` are like `any` and `all` but they take a condition expression that is used against each element to determine if it's `true`. Note: in `jq` you can simply pass a condition to `any` or `all` and it simply works - `yq` isn't that clever..yet
These are most commonly used with the `select` operator to filter particular nodes.
## `or` example
Running
```bash
yq eval --null-input 'true or false'
```
will output
```yaml
true
```
## `and` example
Running
```bash
yq eval --null-input 'true and false'
```
will output
```yaml
false
```
## Matching nodes with select, equals and or
Given a sample.yml file of:
```yaml
- a: bird
b: dog
- a: frog
b: bird
- a: cat
b: fly
```
then
```bash
yq eval '[.[] | select(.a == "cat" or .b == "dog")]' sample.yml
```
will output
```yaml
- a: bird
b: dog
- a: cat
b: fly
```
## `any` returns true if any boolean in a given array is true
Given a sample.yml file of:
```yaml
- false
- true
```
then
```bash
yq eval 'any' sample.yml
```
will output
```yaml
true
```
## `any` returns false for an empty array
Given a sample.yml file of:
```yaml
[]
```
then
```bash
yq eval 'any' sample.yml
```
will output
```yaml
false
```
## `any_c` returns true if any element in the array is true for the given condition.
Given a sample.yml file of:
```yaml
a:
- rad
- awesome
b:
- meh
- whatever
```
then
```bash
yq eval '.[] |= any_c(. == "awesome")' sample.yml
```
will output
```yaml
a: true
b: false
```
## `all` returns true if all booleans in a given array are true
Given a sample.yml file of:
```yaml
- true
- true
```
then
```bash
yq eval 'all' sample.yml
```
will output
```yaml
true
```
## `all` returns true for an empty array
Given a sample.yml file of:
```yaml
[]
```
then
```bash
yq eval 'all' sample.yml
```
will output
```yaml
true
```
## `all_c` returns true if all elements in the array are true for the given condition.
Given a sample.yml file of:
```yaml
a:
- rad
- awesome
b:
- meh
- 12
```
then
```bash
yq eval '.[] |= all_c(tag == "!!str")' sample.yml
```
will output
```yaml
a: true
b: false
```
## Not true is false
Running
```bash
yq eval --null-input 'true | not'
```
will output
```yaml
false
```
## Not false is true
Running
```bash
yq eval --null-input 'false | not'
```
will output
```yaml
true
```
## String values considered to be true
Running
```bash
yq eval --null-input '"cat" | not'
```
will output
```yaml
false
```
## Empty string value considered to be true
Running
```bash
yq eval --null-input '"" | not'
```
will output
```yaml
false
```
## Numbers are considered to be true
Running
```bash
yq eval --null-input '1 | not'
```
will output
```yaml
false
```
## Zero is considered to be true
Running
```bash
yq eval --null-input '0 | not'
```
will output
```yaml
false
```
## Null is considered to be false
Running
```bash
yq eval --null-input '~ | not'
```
will output
```yaml
true
```

53
operators/collect-into-array.md Normal file
View File

@ -0,0 +1,53 @@
# Collect into Array
This creates an array using the expression between the square brackets.
## Collect empty
Running
```bash
yq eval --null-input '[]'
```
will output
```yaml
[]
```
## Collect single
Running
```bash
yq eval --null-input '["cat"]'
```
will output
```yaml
- cat
```
## Collect many
Given a sample.yml file of:
```yaml
a: cat
b: dog
```
then
```bash
yq eval '[.a, .b]' sample.yml
```
will output
```yaml
- cat
- dog
```

204
operators/comment-operators.md Normal file
View File

@ -0,0 +1,204 @@
# Comment Operators
Use these comment operators to set or retrieve comments.
Like the `=` and `|=` assign operators, the same syntax applies when updating comments:
### plain form: `=`
This will assign the LHS nodes comments to the expression on the RHS. The RHS is run against the matching nodes in the pipeline
### relative form: `|=`
Similar to the plain form, however the RHS evaluates against each matching LHS node! This is useful if you want to set the comments as a relative expression of the node, for instance its value or path.
## Set line comment
Given a sample.yml file of:
```yaml
a: cat
```
then
```bash
yq eval '.a lineComment="single"' sample.yml
```
will output
```yaml
a: cat # single
```
## Use update assign to perform relative updates
Given a sample.yml file of:
```yaml
a: cat
b: dog
```
then
```bash
yq eval '.. lineComment |= .' sample.yml
```
will output
```yaml
a: cat # cat
b: dog # dog
```
## Set head comment
Given a sample.yml file of:
```yaml
a: cat
```
then
```bash
yq eval '. headComment="single"' sample.yml
```
will output
```yaml
# single
a: cat
```
## Set foot comment, using an expression
Given a sample.yml file of:
```yaml
a: cat
```
then
```bash
yq eval '. footComment=.a' sample.yml
```
will output
```yaml
a: cat
# cat
```
## Remove comment
Given a sample.yml file of:
```yaml
a: cat # comment
b: dog # leave this
```
then
```bash
yq eval '.a lineComment=""' sample.yml
```
will output
```yaml
a: cat
b: dog # leave this
```
## Remove (strip) all comments
Note the use of `...` to ensure key nodes are included.
Given a sample.yml file of:
```yaml
a: cat # comment
# great
b: # key comment
```
then
```bash
yq eval '... comments=""' sample.yml
```
will output
```yaml
a: cat
b:
```
## Get line comment
Given a sample.yml file of:
```yaml
a: cat # meow
```
then
```bash
yq eval '.a | lineComment' sample.yml
```
will output
```yaml
meow
```
## Get head comment
Given a sample.yml file of:
```yaml
a: cat # meow
```
then
```bash
yq eval '. | headComment' sample.yml
```
will output
```yaml
```
## Get foot comment
Given a sample.yml file of:
```yaml
a: cat # meow
```
then
```bash
yq eval '. | footComment' sample.yml
```
will output
```yaml
```

115
operators/contains.md Normal file
View File

@ -0,0 +1,115 @@
# Contains
## Array contains array
Array is equal or subset of
Given a sample.yml file of:
```yaml
- foobar
- foobaz
- blarp
```
then
```bash
yq eval 'contains(["baz", "bar"])' sample.yml
```
will output
```yaml
true
```
## Object included in array
Given a sample.yml file of:
```yaml
"foo": 12
"bar":
- 1
- 2
- "barp": 12
"blip": 13
```
then
```bash
yq eval 'contains({"bar": [{"barp": 12}]})' sample.yml
```
will output
```yaml
true
```
## Object not included in array
Given a sample.yml file of:
```yaml
"foo": 12
"bar":
- 1
- 2
- "barp": 12
"blip": 13
```
then
```bash
yq eval 'contains({"foo": 12, "bar": [{"barp": 15}]})' sample.yml
```
will output
```yaml
false
```
## String contains substring
Given a sample.yml file of:
```yaml
foobar
```
then
```bash
yq eval 'contains("bar")' sample.yml
```
will output
```yaml
true
```
## String equals string
Given a sample.yml file of:
```yaml
meow
```
then
```bash
yq eval 'contains("meow")' sample.yml
```
will output
```yaml
true
```

107
operators/create-collect-into-object.md Normal file
View File

@ -0,0 +1,107 @@
# Create, Collect into Object
This is used to construct objects (or maps). This can be used against existing yaml, or to create fresh yaml documents.
## Collect empty object
Running
```bash
yq eval --null-input '{}'
```
will output
```yaml
{}
```
## Wrap (prefix) existing object
Given a sample.yml file of:
```yaml
name: Mike
```
then
```bash
yq eval '{"wrap": .}' sample.yml
```
will output
```yaml
wrap:
name: Mike
```
## Using splat to create multiple objects
Given a sample.yml file of:
```yaml
name: Mike
pets:
- cat
- dog
```
then
```bash
yq eval '{.name: .pets.[]}' sample.yml
```
will output
```yaml
Mike: cat
Mike: dog
```
## Working with multiple documents
Given a sample.yml file of:
```yaml
name: Mike
pets:
- cat
- dog
---
name: Rosey
pets:
- monkey
- sheep
```
then
```bash
yq eval '{.name: .pets.[]}' sample.yml
```
will output
```yaml
Mike: cat
Mike: dog
Rosey: monkey
Rosey: sheep
```
## Creating yaml from scratch
Running
```bash
yq eval --null-input '{"wrap": "frog"}'
```
will output
```yaml
wrap: frog
```

161
operators/delete.md Normal file
View File

@ -0,0 +1,161 @@
# Delete
Deletes matching entries in maps or arrays.
## Delete entry in map
Given a sample.yml file of:
```yaml
a: cat
b: dog
```
then
```bash
yq eval 'del(.b)' sample.yml
```
will output
```yaml
a: cat
```
## Delete nested entry in map
Given a sample.yml file of:
```yaml
a:
a1: fred
a2: frood
```
then
```bash
yq eval 'del(.a.a1)' sample.yml
```
will output
```yaml
a:
a2: frood
```
## Delete entry in array
Given a sample.yml file of:
```yaml
- 1
- 2
- 3
```
then
```bash
yq eval 'del(.[1])' sample.yml
```
will output
```yaml
- 1
- 3
```
## Delete nested entry in array
Given a sample.yml file of:
```yaml
- a: cat
b: dog
```
then
```bash
yq eval 'del(.[0].a)' sample.yml
```
will output
```yaml
- b: dog
```
## Delete no matches
Given a sample.yml file of:
```yaml
a: cat
b: dog
```
then
```bash
yq eval 'del(.c)' sample.yml
```
will output
```yaml
a: cat
b: dog
```
## Delete matching entries
Given a sample.yml file of:
```yaml
a: cat
b: dog
c: bat
```
then
```bash
yq eval 'del( .[] | select(. == "*at") )' sample.yml
```
will output
```yaml
b: dog
```
## Recursively delete matching keys
Given a sample.yml file of:
```yaml
a:
name: frog
b:
name: blog
age: 12
```
then
```bash
yq eval 'del(.. | select(has("name")).name)' sample.yml
```
will output
```yaml
a:
b:
age: 12
```

120
operators/document-index.md Normal file
View File

@ -0,0 +1,120 @@
# Document Index
Use the `documentIndex` operator (or the `di` shorthand) to select nodes of a particular document.
## Retrieve a document index
Given a sample.yml file of:
```yaml
a: cat
---
a: frog
```
then
```bash
yq eval '.a | documentIndex' sample.yml
```
will output
```yaml
0
---
1
```
## Retrieve a document index, shorthand
Given a sample.yml file of:
```yaml
a: cat
---
a: frog
```
then
```bash
yq eval '.a | di' sample.yml
```
will output
```yaml
0
---
1
```
## Filter by document index
Given a sample.yml file of:
```yaml
a: cat
---
a: frog
```
then
```bash
yq eval 'select(documentIndex == 1)' sample.yml
```
will output
```yaml
a: frog
```
## Filter by document index shorthand
Given a sample.yml file of:
```yaml
a: cat
---
a: frog
```
then
```bash
yq eval 'select(di == 1)' sample.yml
```
will output
```yaml
a: frog
```
## Print Document Index with matches
Given a sample.yml file of:
```yaml
a: cat
---
a: frog
```
then
```bash
yq eval '.a | ({"match": ., "doc": documentIndex})' sample.yml
```
will output
```yaml
match: cat
doc: 0
match: frog
doc: 1
```

162
operators/entries.md Normal file
View File

@ -0,0 +1,162 @@
# Entries
Similar to the same named functions in `jq` these functions convert to/from an object and an array of key-value pairs. This is most useful for performing operations on keys of maps.
## to\_entries Map
Given a sample.yml file of:
```yaml
a: 1
b: 2
```
then
```bash
yq eval 'to_entries' sample.yml
```
will output
```yaml
- key: a
value: 1
- key: b
value: 2
```
## to\_entries Array
Given a sample.yml file of:
```yaml
- a
- b
```
then
```bash
yq eval 'to_entries' sample.yml
```
will output
```yaml
- key: 0
value: a
- key: 1
value: b
```
## to\_entries null
Given a sample.yml file of:
```yaml
null
```
then
```bash
yq eval 'to_entries' sample.yml
```
will output
```yaml
```
## from\_entries map
Given a sample.yml file of:
```yaml
a: 1
b: 2
```
then
```bash
yq eval 'to_entries | from_entries' sample.yml
```
will output
```yaml
a: 1
b: 2
```
## from\_entries with numeric key indexes
from\_entries always creates a map, even for numeric keys
Given a sample.yml file of:
```yaml
- a
- b
```
then
```bash
yq eval 'to_entries | from_entries' sample.yml
```
will output
```yaml
0: a
1: b
```
## Use with\_entries to update keys
Given a sample.yml file of:
```yaml
a: 1
b: 2
```
then
```bash
yq eval 'with_entries(.key |= "KEY_" + .)' sample.yml
```
will output
```yaml
KEY_a: 1
KEY_b: 2
```
## Use with\_entries to filter the map
Given a sample.yml file of:
```yaml
a:
b: bird
c:
d: dog
```
then
```bash
yq eval 'with_entries(select(.value | has("b")))' sample.yml
```
will output
```yaml
a:
b: bird
```

108
operators/env-variable-operators.md Normal file
View File

@ -0,0 +1,108 @@
# Env Variable Operators
This operator is used to handle environment variables usage in path expressions. While environment variables can, of course, be passed in via your CLI with string interpolation, this often comes with complex quote escaping and can be tricky to write and read. Note that there are two forms, `env` which will parse the environment variable as a yaml (be it a map, array, string, number of boolean) and `strenv` which will always parse the argument as a string.
## Read string environment variable
Running
```bash
myenv="cat meow" yq eval --null-input '.a = env(myenv)'
```
will output
```yaml
a: cat meow
```
## Read boolean environment variable
Running
```bash
myenv="true" yq eval --null-input '.a = env(myenv)'
```
will output
```yaml
a: true
```
## Read numeric environment variable
Running
```bash
myenv="12" yq eval --null-input '.a = env(myenv)'
```
will output
```yaml
a: 12
```
## Read yaml environment variable
Running
```bash
myenv="{b: fish}" yq eval --null-input '.a = env(myenv)'
```
will output
```yaml
a: {b: fish}
```
## Read boolean environment variable as a string
Running
```bash
myenv="true" yq eval --null-input '.a = strenv(myenv)'
```
will output
```yaml
a: "true"
```
## Read numeric environment variable as a string
Running
```bash
myenv="12" yq eval --null-input '.a = strenv(myenv)'
```
will output
```yaml
a: "12"
```
## Dynamic key lookup with environment variable
Given a sample.yml file of:
```yaml
cat: meow
dog: woof
```
then
```bash
myenv="cat" yq eval '.[env(myenv)]' sample.yml
```
will output
```yaml
meow
```

163
operators/equals.md Normal file
View File

@ -0,0 +1,163 @@
# Equals
This is a boolean operator that will return `true` if the LHS is equal to the RHS and `false` otherwise.
```
.a == .b
```
It is most often used with the select operator to find particular nodes:
```
select(.a == .b)
```
## Match string
Given a sample.yml file of:
```yaml
- cat
- goat
- dog
```
then
```bash
yq eval '.[] | (. == "*at")' sample.yml
```
will output
```yaml
true
true
false
```
## Don't match string
Given a sample.yml file of:
```yaml
- cat
- goat
- dog
```
then
```bash
yq eval '.[] | (. != "*at")' sample.yml
```
will output
```yaml
false
false
true
```
## Match number
Given a sample.yml file of:
```yaml
- 3
- 4
- 5
```
then
```bash
yq eval '.[] | (. == 4)' sample.yml
```
will output
```yaml
false
true
false
```
## Dont match number
Given a sample.yml file of:
```yaml
- 3
- 4
- 5
```
then
```bash
yq eval '.[] | (. != 4)' sample.yml
```
will output
```yaml
true
false
true
```
## Match nulls
Running
```bash
yq eval --null-input 'null == ~'
```
will output
```yaml
true
```
## Non exisitant key doesn't equal a value
Given a sample.yml file of:
```yaml
a: frog
```
then
```bash
yq eval 'select(.b != "thing")' sample.yml
```
will output
```yaml
a: frog
```
## Two non existant keys are equal
Given a sample.yml file of:
```yaml
a: frog
```
then
```bash
yq eval 'select(.b == .c)' sample.yml
```
will output
```yaml
a: frog
```

101
operators/file-operators.md Normal file
View File

@ -0,0 +1,101 @@
# File Operators
File operators are most often used with merge when needing to merge specific files together. Note that when doing this, you will need to use `eval-all` to ensure all yaml documents are loaded into memory before performing the merge (as opposed to `eval` which runs the expression once per document).
Note that the `fileIndex` operator has a short alias of `fi`.
## Merging files
Note the use of eval-all to ensure all documents are loaded into memory.
```bash
yq eval-all 'select(fi == 0) * select(filename == "file2.yaml")' file1.yaml file2.yaml
```
## Get filename
Given a sample.yml file of:
```yaml
a: cat
```
then
```bash
yq eval 'filename' sample.yml
```
will output
```yaml
sample.yml
```
## Get file index
Given a sample.yml file of:
```yaml
a: cat
```
then
```bash
yq eval 'fileIndex' sample.yml
```
will output
```yaml
0
```
## Get file indices of multiple documents
Given a sample.yml file of:
```yaml
a: cat
```
And another sample another.yml file of:
```yaml
a: cat
```
then
```bash
yq eval-all 'fileIndex' sample.yml another.yml
```
will output
```yaml
0
---
1
```
## Get file index alias
Given a sample.yml file of:
```yaml
a: cat
```
then
```bash
yq eval 'fi' sample.yml
```
will output
```yaml
0
```

86
operators/has.md Normal file
View File

@ -0,0 +1,86 @@
# Has
This is operation that returns true if the key exists in a map (or index in an array), false otherwise.
## Has map key
Given a sample.yml file of:
```yaml
- a: yes
- a: ~
- a:
- b: nope
```
then
```bash
yq eval '.[] | has("a")' sample.yml
```
will output
```yaml
true
true
true
false
```
## Select, checking for existence of deep paths
Simply pipe in parent expressions into `has`
Given a sample.yml file of:
```yaml
- a:
b:
c: cat
- a:
b:
d: dog
```
then
```bash
yq eval '.[] | select(.a.b | has("c"))' sample.yml
```
will output
```yaml
a:
b:
c: cat
```
## Has array index
Given a sample.yml file of:
```yaml
- []
- [1]
- [1, 2]
- [1, null]
- [1, 2, 3]
```
then
```bash
yq eval '.[] | has(1)' sample.yml
```
will output
```yaml
false
false
true
true
true
```

47
operators/keys.md Normal file
View File

@ -0,0 +1,47 @@
# Keys
Use the `keys` operator to return map keys or array indices.
## Map keys
Given a sample.yml file of:
```yaml
dog: woof
cat: meow
```
then
```bash
yq eval 'keys' sample.yml
```
will output
```yaml
- dog
- cat
```
## Array keys
Given a sample.yml file of:
```yaml
- apple
- banana
```
then
```bash
yq eval 'keys' sample.yml
```
will output
```yaml
- 0
- 1
```

93
operators/length.md Normal file
View File

@ -0,0 +1,93 @@
# Length
Returns the lengths of the nodes. Length is defined according to the type of the node.
## String length
returns length of string
Given a sample.yml file of:
```yaml
a: cat
```
then
```bash
yq eval '.a | length' sample.yml
```
will output
```yaml
3
```
## null length
Given a sample.yml file of:
```yaml
a: null
```
then
```bash
yq eval '.a | length' sample.yml
```
will output
```yaml
0
```
## Map length
returns number of entries
Given a sample.yml file of:
```yaml
a: cat
c: dog
```
then
```bash
yq eval 'length' sample.yml
```
will output
```yaml
2
```
## Array length
returns number of elements
Given a sample.yml file of:
```yaml
- 2
- 4
- 6
- 8
```
then
```bash
yq eval 'length' sample.yml
```
will output
```yaml
4
```

450
operators/multiply-merge.md Normal file
View File

@ -0,0 +1,450 @@
# Multiply (Merge)
Like the multiple operator in jq, depending on the operands, this multiply operator will do different things. Currently numbers, arrays and objects are supported.
## Objects and arrays - merging
Objects are merged deeply matching on matching keys. By default, array values override and are not deeply merged.
Note that when merging objects, this operator returns the merged object (not the parent). This will be clearer in the examples below.
### Merge Flags
You can control how objects are merged by using one or more of the following flags. Multiple flags can be used together, e.g. `.a *+? .b`. See examples below
* `+` to append arrays
* `?` to only merge existing fields
* `d` to deeply merge arrays
### Merging files
Note the use of `eval-all` to ensure all documents are loaded into memory.
```bash
yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' file1.yaml file2.yaml
```
## Multiply integers
Running
```bash
yq eval --null-input '3 * 4'
```
will output
```yaml
12
```
## Merge objects together, returning merged result only
Given a sample.yml file of:
```yaml
a:
field: me
fieldA: cat
b:
field:
g: wizz
fieldB: dog
```
then
```bash
yq eval '.a * .b' sample.yml
```
will output
```yaml
field:
g: wizz
fieldA: cat
fieldB: dog
```
## Merge objects together, returning parent object
Given a sample.yml file of:
```yaml
a:
field: me
fieldA: cat
b:
field:
g: wizz
fieldB: dog
```
then
```bash
yq eval '. * {"a":.b}' sample.yml
```
will output
```yaml
a:
field:
g: wizz
fieldA: cat
fieldB: dog
b:
field:
g: wizz
fieldB: dog
```
## Merge keeps style of LHS
Given a sample.yml file of:
```yaml
a: {things: great}
b:
also: "me"
```
then
```bash
yq eval '. * {"a":.b}' sample.yml
```
will output
```yaml
a: {things: great, also: "me"}
b:
also: "me"
```
## Merge arrays
Given a sample.yml file of:
```yaml
a:
- 1
- 2
- 3
b:
- 3
- 4
- 5
```
then
```bash
yq eval '. * {"a":.b}' sample.yml
```
will output
```yaml
a:
- 3
- 4
- 5
b:
- 3
- 4
- 5
```
## Merge, only existing fields
Given a sample.yml file of:
```yaml
a:
thing: one
cat: frog
b:
missing: two
thing: two
```
then
```bash
yq eval '.a *? .b' sample.yml
```
will output
```yaml
thing: two
cat: frog
```
## Merge, appending arrays
Given a sample.yml file of:
```yaml
a:
array:
- 1
- 2
- animal: dog
value: coconut
b:
array:
- 3
- 4
- animal: cat
value: banana
```
then
```bash
yq eval '.a *+ .b' sample.yml
```
will output
```yaml
array:
- 1
- 2
- animal: dog
- 3
- 4
- animal: cat
value: banana
```
## Merge, only existing fields, appending arrays
Given a sample.yml file of:
```yaml
a:
thing:
- 1
- 2
b:
thing:
- 3
- 4
another:
- 1
```
then
```bash
yq eval '.a *?+ .b' sample.yml
```
will output
```yaml
thing:
- 1
- 2
- 3
- 4
```
## Merge, deeply merging arrays
Merging arrays deeply means arrays are merge like objects, with indexes as their key. In this case, we merge the first item in the array, and do nothing with the second.
Given a sample.yml file of:
```yaml
a:
- name: fred
age: 12
- name: bob
age: 32
b:
- name: fred
age: 34
```
then
```bash
yq eval '.a *d .b' sample.yml
```
will output
```yaml
- name: fred
age: 34
- name: bob
age: 32
```
## Merge arrays of objects together, matching on a key
It's a complex command, the trickyness comes from needing to have the right context in the expressions. First we save the second array into a variable '$two' which lets us reference it later. We then need to update the first array. We will use the relative update (|=) because we need to update relative to the current element of the array in the LHS in the RHS expression. We set the current element of the first array as $cur. Now we multiply (merge) $cur with the matching entry in $two, by passing $two through a select filter.
Given a sample.yml file of:
```yaml
- a: apple
b: appleB
- a: kiwi
b: kiwiB
- a: banana
b: bananaB
```
And another sample another.yml file of:
```yaml
- a: banana
c: bananaC
- a: apple
b: appleB2
- a: dingo
c: dingoC
```
then
```bash
yq eval-all '(select(fi==1) | .[]) as $two | select(fi==0) | .[] |= (. as $cur | $cur * ($two | select(.a == $cur.a)))' sample.yml another.yml
```
will output
```yaml
- a: apple
b: appleB2
- a: kiwi
b: kiwiB
- a: banana
b: bananaB
c: bananaC
```
## Merge to prefix an element
Given a sample.yml file of:
```yaml
a: cat
b: dog
```
then
```bash
yq eval '. * {"a": {"c": .a}}' sample.yml
```
will output
```yaml
a:
c: cat
b: dog
```
## Merge with simple aliases
Given a sample.yml file of:
```yaml
a: &cat
c: frog
b:
f: *cat
c:
g: thongs
```
then
```bash
yq eval '.c * .b' sample.yml
```
will output
```yaml
g: thongs
f: *cat
```
## Merge copies anchor names
Given a sample.yml file of:
```yaml
a:
c: &cat frog
b:
f: *cat
c:
g: thongs
```
then
```bash
yq eval '.c * .a' sample.yml
```
will output
```yaml
g: thongs
c: &cat frog
```
## Merge with merge anchors
Given a sample.yml file of:
```yaml
foo: &foo
a: foo_a
thing: foo_thing
c: foo_c
bar: &bar
b: bar_b
thing: bar_thing
c: bar_c
foobarList:
b: foobarList_b
!!merge <<:
- *foo
- *bar
c: foobarList_c
foobar:
c: foobar_c
!!merge <<: *foo
thing: foobar_thing
```
then
```bash
yq eval '.foobar * .foobarList' sample.yml
```
will output
```yaml
c: foobarList_c
<<:
- *foo
- *bar
thing: foobar_thing
b: foobarList_b
```

123
operators/path.md Normal file
View File

@ -0,0 +1,123 @@
# Path
The path operator can be used to get the traversal paths of matching nodes in an expression. The path is returned as an array, which if traversed in order will lead to the matching node.
You can get the key/index of matching nodes by using the `path` operator to return the path array then piping that through `.[-1]` to get the last element of that array, the key.
## Map path
Given a sample.yml file of:
```yaml
a:
b: cat
```
then
```bash
yq eval '.a.b | path' sample.yml
```
will output
```yaml
- a
- b
```
## Get map key
Given a sample.yml file of:
```yaml
a:
b: cat
```
then
```bash
yq eval '.a.b | path | .[-1]' sample.yml
```
will output
```yaml
b
```
## Array path
Given a sample.yml file of:
```yaml
a:
- cat
- dog
```
then
```bash
yq eval '.a.[] | select(. == "dog") | path' sample.yml
```
will output
```yaml
- a
- 1
```
## Get array index
Given a sample.yml file of:
```yaml
a:
- cat
- dog
```
then
```bash
yq eval '.a.[] | select(. == "dog") | path | .[-1]' sample.yml
```
will output
```yaml
1
```
## Print path and value
Given a sample.yml file of:
```yaml
a:
- cat
- dog
- frog
```
then
```bash
yq eval '.a.[] | select(. == "*og") | [{"path":path, "value":.}]' sample.yml
```
will output
```yaml
- path:
- a
- 1
value: dog
- path:
- a
- 2
value: frog
```

48
operators/pipe.md Normal file
View File

@ -0,0 +1,48 @@
# Pipe
Pipe the results of an expression into another. Like the bash operator.
## Simple Pipe
Given a sample.yml file of:
```yaml
a:
b: cat
```
then
```bash
yq eval '.a | .b' sample.yml
```
will output
```yaml
cat
```
## Multiple updates
Given a sample.yml file of:
```yaml
a: cow
b: sheep
c: same
```
then
```bash
yq eval '.a = "cat" | .b = "dog"' sample.yml
```
will output
```yaml
a: cat
b: dog
c: same
```

194
operators/recursive-descent-glob.md Normal file
View File

@ -0,0 +1,194 @@
# Recursive Descent (Glob)
This operator recursively matches (or globs) all children nodes given of a particular element, including that node itself. This is most often used to apply a filter recursively against all matches. It can be used in either the
## match values form `..`
This will, like the `jq` equivalent, recursively match all _value_ nodes. Use it to find/manipulate particular values.
For instance to set the `style` of all _value_ nodes in a yaml doc, excluding map keys:
```bash
yq eval '.. style= "flow"' file.yaml
```
## match values and map keys form `...`
The also includes map keys in the results set. This is particularly useful in YAML as unlike JSON, map keys can have their own styling, tags and use anchors and aliases.
For instance to set the `style` of all nodes in a yaml doc, including the map keys:
```bash
yq eval '... style= "flow"' file.yaml
```
## Recurse map (values only)
Given a sample.yml file of:
```yaml
a: frog
```
then
```bash
yq eval '..' sample.yml
```
will output
```yaml
a: frog
frog
```
## Recursively find nodes with keys
Note that this example has wrapped the expression in `[]` to show that there are two matches returned. You do not have to wrap in `[]` in your path expression.
Given a sample.yml file of:
```yaml
a:
name: frog
b:
name: blog
age: 12
```
then
```bash
yq eval '[.. | select(has("name"))]' sample.yml
```
will output
```yaml
- name: frog
b:
name: blog
age: 12
- name: blog
age: 12
```
## Recursively find nodes with values
Given a sample.yml file of:
```yaml
a:
nameA: frog
b:
nameB: frog
age: 12
```
then
```bash
yq eval '.. | select(. == "frog")' sample.yml
```
will output
```yaml
frog
frog
```
## Recurse map (values and keys)
Note that the map key appears in the results
Given a sample.yml file of:
```yaml
a: frog
```
then
```bash
yq eval '...' sample.yml
```
will output
```yaml
a: frog
a
frog
```
## Aliases are not traversed
Given a sample.yml file of:
```yaml
a: &cat
c: frog
b: *cat
```
then
```bash
yq eval '[..]' sample.yml
```
will output
```yaml
- a: &cat
c: frog
b: *cat
- &cat
c: frog
- frog
- *cat
```
## Merge docs are not traversed
Given a sample.yml file of:
```yaml
foo: &foo
a: foo_a
thing: foo_thing
c: foo_c
bar: &bar
b: bar_b
thing: bar_thing
c: bar_c
foobarList:
b: foobarList_b
!!merge <<:
- *foo
- *bar
c: foobarList_c
foobar:
c: foobar_c
!!merge <<: *foo
thing: foobar_thing
```
then
```bash
yq eval '.foobar | [..]' sample.yml
```
will output
```yaml
- c: foobar_c
!!merge <<: *foo
thing: foobar_thing
- foobar_c
- *foo
- foobar_thing
```

97
operators/reduce.md Normal file
View File

@ -0,0 +1,97 @@
# Reduce
Reduce is a powerful way to process a collection of data into a new form.
```
<exp> as $<name> ireduce (<init>; <block>)
```
e.g.
```
.[] as $item ireduce (0; . + $item)
```
On the LHS we are configuring the collection of items that will be reduced `<exp>` as well as what each element will be called `$<name>`. Note that the array has been splatted into its individual elements.
On the RHS there is `<init>`, the starting value of the accumulator and `<block>`, the expression that will update the accumulator for each element in the collection. Note that within the block expression, `.` will evaluate to the current value of the accumulator.
## yq vs jq syntax
Reduce syntax in `yq` is a little different from `jq` - as `yq` (currently) isn't as sophisticated as `jq` and its only supports infix notation (e.g. a + b, where the operator is in the middle of the two parameters) - where as `jq` uses a mix of infix notation with _prefix_ notation (e.g. `reduce a b` is like writing `+ a b`).
To that end, the reduce operator is called `ireduce` for backwards compatability if a `jq` like prefix version of `reduce` is ever added.
## Sum numbers
Given a sample.yml file of:
```yaml
- 10
- 2
- 5
- 3
```
then
```bash
yq eval '.[] as $item ireduce (0; . + $item)' sample.yml
```
will output
```yaml
20
```
## Merge all yaml files together
Given a sample.yml file of:
```yaml
a: cat
```
And another sample another.yml file of:
```yaml
b: dog
```
then
```bash
yq eval-all '. as $item ireduce ({}; . * $item )' sample.yml another.yml
```
will output
```yaml
a: cat
b: dog
```
## Convert an array to an object
Given a sample.yml file of:
```yaml
- name: Cathy
has: apples
- name: Bob
has: bananas
```
then
```bash
yq eval '.[] as $item ireduce ({}; .[$item | .name] = ($item | .has) )' sample.yml
```
will output
```yaml
Cathy: apples
Bob: bananas
```

52
operators/select.md Normal file
View File

@ -0,0 +1,52 @@
# Select
Select is used to filter arrays and maps by a boolean expression.
## Select elements from array
Given a sample.yml file of:
```yaml
- cat
- goat
- dog
```
then
```bash
yq eval '.[] | select(. == "*at")' sample.yml
```
will output
```yaml
cat
goat
```
## Select and update matching values in map
Given a sample.yml file of:
```yaml
a:
things: cat
bob: goat
horse: dog
```
then
```bash
yq eval '(.a.[] | select(. == "*at")) |= "rabbit"' sample.yml
```
will output
```yaml
a:
things: rabbit
bob: rabbit
horse: dog
```

81
operators/sort-keys.md Normal file
View File

@ -0,0 +1,81 @@
# Sort Keys
The Sort Keys operator sorts maps by their keys (based on their string value). This operator does not do anything to arrays or scalars (so you can easily recursively apply it to all maps).
Sort is particularly useful for diffing two different yaml documents:
```bash
yq eval -i 'sortKeys(..)' file1.yml
yq eval -i 'sortKeys(..)' file2.yml
diff file1.yml file2.yml
```
## Sort keys of map
Given a sample.yml file of:
```yaml
c: frog
a: blah
b: bing
```
then
```bash
yq eval 'sortKeys(.)' sample.yml
```
will output
```yaml
a: blah
b: bing
c: frog
```
## Sort keys recursively
Note the array elements are left unsorted, but maps inside arrays are sorted
Given a sample.yml file of:
```yaml
bParent:
c: dog
array:
- 3
- 1
- 2
aParent:
z: donkey
x:
- c: yum
b: delish
- b: ew
a: apple
```
then
```bash
yq eval 'sortKeys(..)' sample.yml
```
will output
```yaml
aParent:
x:
- b: delish
c: yum
- a: apple
b: ew
z: donkey
bParent:
array:
- 3
- 1
- 2
c: dog
```

39
operators/split-into-documents.md Normal file
View File

@ -0,0 +1,39 @@
# Split into Documents
This operator splits all matches into separate documents
## Split empty
Running
```bash
yq eval --null-input 'splitDoc'
```
will output
```yaml
```
## Split array
Given a sample.yml file of:
```yaml
- a: cat
- b: dog
```
then
```bash
yq eval '.[] | splitDoc' sample.yml
```
will output
```yaml
a: cat
---
b: dog
```

376
operators/string-operators.md Normal file
View File

@ -0,0 +1,376 @@
# String Operators
## String Operators
### RegEx
This uses golangs native regex functions under the hood - See [https://github.com/google/re2/wiki/Syntax](https://github.com/google/re2/wiki/Syntax) for the supported syntax.
## String blocks, bash and newlines
Bash is notorious for chomping on precious trailing newline characters, making it tricky to set strings with newlines properly. In particular, the `$( exp )` _will trim trailing newlines_.
For instance to get this yaml:
```
a: |
cat
```
Using `$( exp )` wont work, as it will trim the trailing new line.
```
m=$(echo "cat\n") yq e -n '.a = strenv(m)'
a: cat
```
However, using printf works:
```
printf -v m "cat\n" ; m="$m" yq e -n '.a = strenv(m)'
a: |
cat
```
As well as having multiline expressions:
```
m="cat
" yq e -n '.a = strenv(m)'
a: |
cat
```
Similarly, if you're trying to set the content from a file, and want a trailing new line:
```
IFS= read -rd '' output < <(cat my_file)
output=$output ./yq e '.data.values = strenv(output)' first.yml
```
### Join strings
Given a sample.yml file of:
```yaml
- cat
- meow
- 1
- null
- true
```
then
```bash
yq eval 'join("; ")' sample.yml
```
will output
```yaml
cat; meow; 1; ; true
```
### Match string
Given a sample.yml file of:
```yaml
foo bar foo
```
then
```bash
yq eval 'match("foo")' sample.yml
```
will output
```yaml
string: foo
offset: 0
length: 3
captures: []
```
### Match string, case insensitive
Given a sample.yml file of:
```yaml
foo bar FOO
```
then
```bash
yq eval '[match("(?i)foo"; "g")]' sample.yml
```
will output
```yaml
- string: foo
offset: 0
length: 3
captures: []
- string: FOO
offset: 8
length: 3
captures: []
```
### Match with capture groups
Given a sample.yml file of:
```yaml
abc abc
```
then
```bash
yq eval '[match("(abc)+"; "g")]' sample.yml
```
will output
```yaml
- string: abc
offset: 0
length: 3
captures:
- string: abc
offset: 0
length: 3
- string: abc
offset: 4
length: 3
captures:
- string: abc
offset: 4
length: 3
```
### Match with named capture groups
Given a sample.yml file of:
```yaml
foo bar foo foo foo
```
then
```bash
yq eval '[match("foo (?P<bar123>bar)? foo"; "g")]' sample.yml
```
will output
```yaml
- string: foo bar foo
offset: 0
length: 11
captures:
- string: bar
offset: 4
length: 3
name: bar123
- string: foo foo
offset: 12
length: 8
captures:
- string: null
offset: -1
length: 0
name: bar123
```
### Capture named groups into a map
Given a sample.yml file of:
```yaml
xyzzy-14
```
then
```bash
yq eval 'capture("(?P<a>[a-z]+)-(?P<n>[0-9]+)")' sample.yml
```
will output
```yaml
a: xyzzy
n: "14"
```
### Match without global flag
Given a sample.yml file of:
```yaml
cat cat
```
then
```bash
yq eval 'match("cat")' sample.yml
```
will output
```yaml
string: cat
offset: 0
length: 3
captures: []
```
### Match with global flag
Given a sample.yml file of:
```yaml
cat cat
```
then
```bash
yq eval '[match("cat"; "g")]' sample.yml
```
will output
```yaml
- string: cat
offset: 0
length: 3
captures: []
- string: cat
offset: 4
length: 3
captures: []
```
### Test using regex
Like jq'q equivalant, this works like match but only returns true/false instead of full match details
Given a sample.yml file of:
```yaml
- cat
- dog
```
then
```bash
yq eval '.[] | test("at")' sample.yml
```
will output
```yaml
true
false
```
### Substitute / Replace string
This uses golang regex, described [here](https://github.com/google/re2/wiki/Syntax) Note the use of `|=` to run in context of the current string value.
Given a sample.yml file of:
```yaml
a: dogs are great
```
then
```bash
yq eval '.a |= sub("dogs", "cats")' sample.yml
```
will output
```yaml
a: cats are great
```
### Substitute / Replace string with regex
This uses golang regex, described [here](https://github.com/google/re2/wiki/Syntax) Note the use of `|=` to run in context of the current string value.
Given a sample.yml file of:
```yaml
a: cat
b: heat
```
then
```bash
yq eval '.[] |= sub("(a)", "${1}r")' sample.yml
```
will output
```yaml
a: cart
b: heart
```
### Split strings
Given a sample.yml file of:
```yaml
cat; meow; 1; ; true
```
then
```bash
yq eval 'split("; ")' sample.yml
```
will output
```yaml
- cat
- meow
- "1"
- ""
- "true"
```
### Split strings one match
Given a sample.yml file of:
```yaml
word
```
then
```bash
yq eval 'split("; ")' sample.yml
```
will output
```yaml
- word
```

311
operators/style.md Normal file
View File

@ -0,0 +1,311 @@
# Style
The style operator can be used to get or set the style of nodes (e.g. string style, yaml style)
## Update and set style of a particular node (simple)
Given a sample.yml file of:
```yaml
a:
b: thing
c: something
```
then
```bash
yq eval '.a.b = "new" | .a.b style="double"' sample.yml
```
will output
```yaml
a:
b: "new"
c: something
```
## Update and set style of a particular node using path variables
Given a sample.yml file of:
```yaml
a:
b: thing
c: something
```
then
```bash
yq eval 'with(.a.b ; . = "new" | . style="double")' sample.yml
```
will output
```yaml
a:
b: "new"
c: something
```
## Set tagged style
Given a sample.yml file of:
```yaml
a: cat
b: 5
c: 3.2
e: true
```
then
```bash
yq eval '.. style="tagged"' sample.yml
```
will output
```yaml
!!map
a: !!str cat
b: !!int 5
c: !!float 3.2
e: !!bool true
```
## Set double quote style
Given a sample.yml file of:
```yaml
a: cat
b: 5
c: 3.2
e: true
```
then
```bash
yq eval '.. style="double"' sample.yml
```
will output
```yaml
a: "cat"
b: "5"
c: "3.2"
e: "true"
```
## Set double quote style on map keys too
Given a sample.yml file of:
```yaml
a: cat
b: 5
c: 3.2
e: true
```
then
```bash
yq eval '... style="double"' sample.yml
```
will output
```yaml
"a": "cat"
"b": "5"
"c": "3.2"
"e": "true"
```
## Set single quote style
Given a sample.yml file of:
```yaml
a: cat
b: 5
c: 3.2
e: true
```
then
```bash
yq eval '.. style="single"' sample.yml
```
will output
```yaml
a: 'cat'
b: '5'
c: '3.2'
e: 'true'
```
## Set literal quote style
Given a sample.yml file of:
```yaml
a: cat
b: 5
c: 3.2
e: true
```
then
```bash
yq eval '.. style="literal"' sample.yml
```
will output
```yaml
a: |-
cat
b: |-
5
c: |-
3.2
e: |-
true
```
## Set folded quote style
Given a sample.yml file of:
```yaml
a: cat
b: 5
c: 3.2
e: true
```
then
```bash
yq eval '.. style="folded"' sample.yml
```
will output
```yaml
a: >-
cat
b: >-
5
c: >-
3.2
e: >-
true
```
## Set flow quote style
Given a sample.yml file of:
```yaml
a: cat
b: 5
c: 3.2
e: true
```
then
```bash
yq eval '.. style="flow"' sample.yml
```
will output
```yaml
{a: cat, b: 5, c: 3.2, e: true}
```
## Reset style - or pretty print
Set empty (default) quote style, note the usage of `...` to match keys too. Note that there is a `--prettyPrint/-P` short flag for this.
Given a sample.yml file of:
```yaml
a: cat
"b": 5
'c': 3.2
"e": true
```
then
```bash
yq eval '... style=""' sample.yml
```
will output
```yaml
a: cat
b: 5
c: 3.2
e: true
```
## Set style relatively with assign-update
Given a sample.yml file of:
```yaml
a: single
b: double
```
then
```bash
yq eval '.[] style |= .' sample.yml
```
will output
```yaml
a: 'single'
b: "double"
```
## Read style
Given a sample.yml file of:
```yaml
{a: "cat", b: 'thing'}
```
then
```bash
yq eval '.. | style' sample.yml
```
will output
```yaml
flow
double
single
```

148
operators/subtract.md Normal file
View File

@ -0,0 +1,148 @@
# Subtract
## Array subtraction
Running
```bash
yq eval --null-input '[1,2] - [2,3]'
```
will output
```yaml
- 1
```
## Array subtraction with nested array
Running
```bash
yq eval --null-input '[[1], 1, 2] - [[1], 3]'
```
will output
```yaml
- 1
- 2
```
## Array subtraction with nested object
Note that order of the keys does not matter
Given a sample.yml file of:
```yaml
- a: b
c: d
- a: b
```
then
```bash
yq eval '. - [{"c": "d", "a": "b"}]' sample.yml
```
will output
```yaml
- a: b
```
## Number subtraction - float
If the lhs or rhs are floats then the expression will be calculated with floats.
Given a sample.yml file of:
```yaml
a: 3
b: 4.5
```
then
```bash
yq eval '.a = .a - .b' sample.yml
```
will output
```yaml
a: -1.5
b: 4.5
```
## Number subtraction - float
If the lhs or rhs are floats then the expression will be calculated with floats.
Given a sample.yml file of:
```yaml
a: 3
b: 4.5
```
then
```bash
yq eval '.a = .a - .b' sample.yml
```
will output
```yaml
a: -1.5
b: 4.5
```
## Number subtraction - int
If both the lhs and rhs are ints then the expression will be calculated with ints.
Given a sample.yml file of:
```yaml
a: 3
b: 4
```
then
```bash
yq eval '.a = .a - .b' sample.yml
```
will output
```yaml
a: -1
b: 4
```
## Decrement numbers
Given a sample.yml file of:
```yaml
a: 3
b: 5
```
then
```bash
yq eval '.[] -= 1' sample.yml
```
will output
```yaml
a: 2
b: 4
```

78
operators/tag.md Normal file
View File

@ -0,0 +1,78 @@
# Tag
The tag operator can be used to get or set the tag of nodes (e.g. `!!str`, `!!int`, `!!bool`).
## Get tag
Given a sample.yml file of:
```yaml
a: cat
b: 5
c: 3.2
e: true
f: []
```
then
```bash
yq eval '.. | tag' sample.yml
```
will output
```yaml
!!map
!!str
!!int
!!float
!!bool
!!seq
```
## Set custom tag
Given a sample.yml file of:
```yaml
a: str
```
then
```bash
yq eval '.a tag = "!!mikefarah"' sample.yml
```
will output
```yaml
a: !!mikefarah str
```
## Find numbers and convert them to strings
Given a sample.yml file of:
```yaml
a: cat
b: 5
c: 3.2
e: true
```
then
```bash
yq eval '(.. | select(tag == "!!int")) tag= "!!str"' sample.yml
```
will output
```yaml
a: cat
b: "5"
c: 3.2
e: true
```

628
operators/traverse-read.md Normal file
View File

@ -0,0 +1,628 @@
# Traverse (Read)
This is the simplest (and perhaps most used) operator, it is used to navigate deeply into yaml structures.
## Simple map navigation
Given a sample.yml file of:
```yaml
a:
b: apple
```
then
```bash
yq eval '.a' sample.yml
```
will output
```yaml
b: apple
```
## Splat
Often used to pipe children into other operators
Given a sample.yml file of:
```yaml
- b: apple
- c: banana
```
then
```bash
yq eval '.[]' sample.yml
```
will output
```yaml
b: apple
c: banana
```
## Optional Splat
Just like splat, but won't error if you run it against scalars
Given a sample.yml file of:
```yaml
cat
```
then
```bash
yq eval '.[]' sample.yml
```
will output
```yaml
```
## Special characters
Use quotes with brackets around path elements with special characters
Given a sample.yml file of:
```yaml
"{}": frog
```
then
```bash
yq eval '.["{}"]' sample.yml
```
will output
```yaml
frog
```
## Nested special characters
Given a sample.yml file of:
```yaml
a:
"key.withdots":
"another.key": apple
```
then
```bash
yq eval '.a["key.withdots"]["another.key"]' sample.yml
```
will output
```yaml
apple
```
## Keys with spaces
Use quotes with brackets around path elements with special characters
Given a sample.yml file of:
```yaml
"red rabbit": frog
```
then
```bash
yq eval '.["red rabbit"]' sample.yml
```
will output
```yaml
frog
```
## Dynamic keys
Expressions within \[] can be used to dynamically lookup / calculate keys
Given a sample.yml file of:
```yaml
b: apple
apple: crispy yum
banana: soft yum
```
then
```bash
yq eval '.[.b]' sample.yml
```
will output
```yaml
crispy yum
```
## Children don't exist
Nodes are added dynamically while traversing
Given a sample.yml file of:
```yaml
c: banana
```
then
```bash
yq eval '.a.b' sample.yml
```
will output
```yaml
null
```
## Optional identifier
Like jq, does not output an error when the yaml is not an array or object as expected
Given a sample.yml file of:
```yaml
- 1
- 2
- 3
```
then
```bash
yq eval '.a?' sample.yml
```
will output
```yaml
```
## Wildcard matching
Given a sample.yml file of:
```yaml
a:
cat: apple
mad: things
```
then
```bash
yq eval '.a."*a*"' sample.yml
```
will output
```yaml
apple
things
```
## Aliases
Given a sample.yml file of:
```yaml
a: &cat
c: frog
b: *cat
```
then
```bash
yq eval '.b' sample.yml
```
will output
```yaml
*cat
```
## Traversing aliases with splat
Given a sample.yml file of:
```yaml
a: &cat
c: frog
b: *cat
```
then
```bash
yq eval '.b[]' sample.yml
```
will output
```yaml
frog
```
## Traversing aliases explicitly
Given a sample.yml file of:
```yaml
a: &cat
c: frog
b: *cat
```
then
```bash
yq eval '.b.c' sample.yml
```
will output
```yaml
frog
```
## Traversing arrays by index
Given a sample.yml file of:
```yaml
- 1
- 2
- 3
```
then
```bash
yq eval '.[0]' sample.yml
```
will output
```yaml
1
```
## Traversing nested arrays by index
Given a sample.yml file of:
```yaml
[[], [cat]]
```
then
```bash
yq eval '.[1][0]' sample.yml
```
will output
```yaml
cat
```
## Maps with numeric keys
Given a sample.yml file of:
```yaml
2: cat
```
then
```bash
yq eval '.[2]' sample.yml
```
will output
```yaml
cat
```
## Maps with non existing numeric keys
Given a sample.yml file of:
```yaml
a: b
```
then
```bash
yq eval '.[0]' sample.yml
```
will output
```yaml
null
```
## Traversing merge anchors
Given a sample.yml file of:
```yaml
foo: &foo
a: foo_a
thing: foo_thing
c: foo_c
bar: &bar
b: bar_b
thing: bar_thing
c: bar_c
foobarList:
b: foobarList_b
!!merge <<:
- *foo
- *bar
c: foobarList_c
foobar:
c: foobar_c
!!merge <<: *foo
thing: foobar_thing
```
then
```bash
yq eval '.foobar.a' sample.yml
```
will output
```yaml
foo_a
```
## Traversing merge anchors with override
Given a sample.yml file of:
```yaml
foo: &foo
a: foo_a
thing: foo_thing
c: foo_c
bar: &bar
b: bar_b
thing: bar_thing
c: bar_c
foobarList:
b: foobarList_b
!!merge <<:
- *foo
- *bar
c: foobarList_c
foobar:
c: foobar_c
!!merge <<: *foo
thing: foobar_thing
```
then
```bash
yq eval '.foobar.c' sample.yml
```
will output
```yaml
foo_c
```
## Traversing merge anchors with local override
Given a sample.yml file of:
```yaml
foo: &foo
a: foo_a
thing: foo_thing
c: foo_c
bar: &bar
b: bar_b
thing: bar_thing
c: bar_c
foobarList:
b: foobarList_b
!!merge <<:
- *foo
- *bar
c: foobarList_c
foobar:
c: foobar_c
!!merge <<: *foo
thing: foobar_thing
```
then
```bash
yq eval '.foobar.thing' sample.yml
```
will output
```yaml
foobar_thing
```
## Splatting merge anchors
Given a sample.yml file of:
```yaml
foo: &foo
a: foo_a
thing: foo_thing
c: foo_c
bar: &bar
b: bar_b
thing: bar_thing
c: bar_c
foobarList:
b: foobarList_b
!!merge <<:
- *foo
- *bar
c: foobarList_c
foobar:
c: foobar_c
!!merge <<: *foo
thing: foobar_thing
```
then
```bash
yq eval '.foobar[]' sample.yml
```
will output
```yaml
foo_c
foo_a
foobar_thing
```
## Traversing merge anchor lists
Note that the later merge anchors override previous
Given a sample.yml file of:
```yaml
foo: &foo
a: foo_a
thing: foo_thing
c: foo_c
bar: &bar
b: bar_b
thing: bar_thing
c: bar_c
foobarList:
b: foobarList_b
!!merge <<:
- *foo
- *bar
c: foobarList_c
foobar:
c: foobar_c
!!merge <<: *foo
thing: foobar_thing
```
then
```bash
yq eval '.foobarList.thing' sample.yml
```
will output
```yaml
bar_thing
```
## Splatting merge anchor lists
Given a sample.yml file of:
```yaml
foo: &foo
a: foo_a
thing: foo_thing
c: foo_c
bar: &bar
b: bar_b
thing: bar_thing
c: bar_c
foobarList:
b: foobarList_b
!!merge <<:
- *foo
- *bar
c: foobarList_c
foobar:
c: foobar_c
!!merge <<: *foo
thing: foobar_thing
```
then
```bash
yq eval '.foobarList[]' sample.yml
```
will output
```yaml
bar_b
foo_a
bar_thing
foobarList_c
```
## Select multiple indices
Given a sample.yml file of:
```yaml
a:
- a
- b
- c
```
then
```bash
yq eval '.a[0, 2]' sample.yml
```
will output
```yaml
a
c
```

42
operators/union.md Normal file
View File

@ -0,0 +1,42 @@
# Union
This operator is used to combine different results together.
## Combine scalars
Running
```bash
yq eval --null-input '1, true, "cat"'
```
will output
```yaml
1
true
cat
```
## Combine selected paths
Given a sample.yml file of:
```yaml
a: fieldA
b: fieldB
c: fieldC
```
then
```bash
yq eval '.a, .c' sample.yml
```
will output
```yaml
fieldA
fieldC
```

107
operators/unique.md Normal file
View File

@ -0,0 +1,107 @@
# Unique
This is used to filter out duplicated items in an array.
## Unique array of scalars (string/numbers)
Given a sample.yml file of:
```yaml
- 1
- 2
- 3
- 2
```
then
```bash
yq eval 'unique' sample.yml
```
will output
```yaml
- 1
- 2
- 3
```
## Unique nulls
Unique works on the node value, so it considers different representations of nulls to be different
Given a sample.yml file of:
```yaml
- ~
- null
- ~
- null
```
then
```bash
yq eval 'unique' sample.yml
```
will output
```yaml
- ~
- null
```
## Unique all nulls
Run against the node tag to unique all the nulls
Given a sample.yml file of:
```yaml
- ~
- null
- ~
- null
```
then
```bash
yq eval 'unique_by(tag)' sample.yml
```
will output
```yaml
- ~
```
## Unique array object fields
Given a sample.yml file of:
```yaml
- name: harry
pet: cat
- name: billy
pet: dog
- name: harry
pet: dog
```
then
```bash
yq eval 'unique_by(.name)' sample.yml
```
will output
```yaml
- name: harry
pet: cat
- name: billy
pet: dog
```

127
operators/variable-operators.md Normal file
View File

@ -0,0 +1,127 @@
# Variable Operators
Like the `jq` equivalents, variables are sometimes required for the more complex expressions (or swapping values between fields).
Note that there is also an additional `ref` operator that holds a reference (instead of a copy) of the path, allowing you to make multiple changes to the same path.
## Single value variable
Given a sample.yml file of:
```yaml
a: cat
```
then
```bash
yq eval '.a as $foo | $foo' sample.yml
```
will output
```yaml
cat
```
## Multi value variable
Given a sample.yml file of:
```yaml
- cat
- dog
```
then
```bash
yq eval '.[] as $foo | $foo' sample.yml
```
will output
```yaml
cat
dog
```
## Using variables as a lookup
Example taken from [jq](https://stedolan.github.io/jq/manual/#Variable/SymbolicBindingOperator:...as$identifier|...)
Given a sample.yml file of:
```yaml
"posts":
- "title": Frist psot
"author": anon
- "title": A well-written article
"author": person1
"realnames":
"anon": Anonymous Coward
"person1": Person McPherson
```
then
```bash
yq eval '.realnames as $names | .posts[] | {"title":.title, "author": $names[.author]}' sample.yml
```
will output
```yaml
title: Frist psot
author: Anonymous Coward
title: A well-written article
author: Person McPherson
```
## Using variables to swap values
Given a sample.yml file of:
```yaml
a: a_value
b: b_value
```
then
```bash
yq eval '.a as $x | .b as $y | .b = $x | .a = $y' sample.yml
```
will output
```yaml
a: b_value
b: a_value
```
## Use ref to reference a path repeatedly
Note: You may find the `with` operator more useful.
Given a sample.yml file of:
```yaml
a:
b: thing
c: something
```
then
```bash
yq eval '.a.b ref $x | $x = "new" | $x style="double"' sample.yml
```
will output
```yaml
a:
b: "new"
c: something
```

81
operators/with.md Normal file
View File

@ -0,0 +1,81 @@
# With
Use the `with` operator to conveniently make multiple updates to a deeply nested path, or to update array elements relatively to each other. The first argument expression sets the root context, and the second expression runs against that root context.
## Update and style
Given a sample.yml file of:
```yaml
a:
deeply:
nested: value
```
then
```bash
yq eval 'with(.a.deeply.nested ; . = "newValue" | . style="single")' sample.yml
```
will output
```yaml
a:
deeply:
nested: 'newValue'
```
## Update multiple deeply nested properties
Given a sample.yml file of:
```yaml
a:
deeply:
nested: value
other: thing
```
then
```bash
yq eval 'with(.a.deeply ; .nested = "newValue" | .other= "newThing")' sample.yml
```
will output
```yaml
a:
deeply:
nested: newValue
other: newThing
```
## Update array elements relatively
The second expression runs with each element of the array as it's contextual root. This allows you to make updates relative to the element.
Given a sample.yml file of:
```yaml
myArray:
- a: apple
- a: banana
```
then
```bash
yq eval 'with(.myArray[] ; .b = .a + " yum")' sample.yml
```
will output
```yaml
myArray:
- a: apple
b: apple yum
- a: banana
b: banana yum
```

236
upgrading-from-v3.md Normal file
View File

@ -0,0 +1,236 @@
# Upgrading from V3
Version 4 of `yq` is quite different from previous versions (and I apologise for that) - however it will be very familiar if you have used `jq` before as it now uses a similar syntax. Most commands that you could do in `v3` are longer in `v4` as a result of having a more expressive syntax language.
Note that `v4` by default now:
* prints all documents of a yaml file.
* prints in color (when outputting to a terminal).
* document separators are printed out by default
## How to do v3 things in v4:
In `v3` yq had seperate commands for reading/writing/deleting and more. In `v4` all these have been embedded into a single expression you specify to either the `eval` command (which runs the expression against each yaml document for each file given in sequence) or the `eval-all` command, which reads all documents of all files, and runs the given expression once.
Many flags from `v3` have been put into the expression language, for instance `stripComments` allowing you to specify which nodes to strip comments from instead of only being able to apply the flag to the entire document.
Lets have a look at the commands for the most common tasks:
### Navigating
v3:
```
yq r sample.yaml 'a.b.c'
```
v4:
```
yq e '.a.b.c' sample.yaml
```
### Reading with default value
v3:
```
yq r sample.yaml --defaultValue frog path.not.there
```
v4: (use the [alternative](broken-reference) operator)
```
yq e '.path.not.there // "frog"' sample.yaml
```
### Finding nodes
v3:
```bash
yq r sample.yaml 'a.(b.d==cat).f'
```
v4:
```bash
yq eval '.a | select(.b.d == "cat") | .f' sample.yaml
```
### Recursively match nodes
v3:
```
yq r sample.yaml 'thing.**.name'
```
v4:
```
yq e '.thing | .. | select(has("name"))' sample.yaml
```
### Multiple documents
v3:
```bash
yq r -d1 sample.yaml 'b.c'
```
v4 (via the document index operator):
```bash
yq eval 'select(documentIndex == 1) | .b.c' sample.yml
```
### Updating / writing documents
v3:
```
yq w sample.yaml 'a.b.c' fred
```
v4:
```
yq eval '.a.b.c = "fred"' sample.yaml
```
### Deleting documents
v3:
```bash
yq d sample.yaml 'a.b.c'
```
v4:
```bash
yq eval 'del(.a.b.c)' sample.yaml
```
### Merging documents
Like `jq`, merge is done via the multiply operator. You will need to use the eval-all command to load all documents into memory at once, and then use the file operator to select the file nodes to merge.
```bash
yq eval-all 'select(fileIndex == 0) * select(filename == "file2.yaml")' file1.yaml file2.yaml
```
### Prefix yaml
Use the [Create / Collect Into Object ](broken-reference)operator to create a new object with the desired prefix.&#x20;
v3:
```
yq p data1.yaml c.d
```
v4:
```
yq eval '{"c": {"d": . }}' data1.yml
```
### Create new yaml documents
Note that in v4 you can no longer run expressions against an empty file to populate it - because the file is empty, there are no matches for `yq` to run through the expression pipeline - for what it's worth, this is what `jq` does as well. Instead use the `--null-input/-n` flag and pipe out the results to the file you want directly (see example below).
v3:
```
yq n b.c cat
```
v4:
```
yq e -n '.b.c = "cat"'
```
### Validate documents
v3:
```
yq validate some.file
```
v4:
```
yq e 'true' some.file > /dev/null
```
Note that passing 'true' as the expression saves having to reencode the yaml (only to pipe it to stdout). In v4 you can also do a slightly more sophisticated validation and assert the tag on the root level, so you can ensure the yaml file is a map or array at the top level:
```
yq e --exit-status 'tag == "!!map" or tag== "!!seq"' some.file > /dev/null
```
### Comparing yaml files
v3:
```
yq compare --prettyPrint file1.yml file2.yml
```
v4:
In v4 there is no built in compare command, instead it relies on using diff. The downside is longer syntax, the upside is that you can use the full power of diff.
```
diff <(yq e -P file1.yml) <(yq e -P file2.yml)
```
### Script files
v3 had a script feature that let you run an array of commands specified in a file in one go. The format for this looked like
```yaml
- command: update
path: a.key1
value: things
- command: delete
path: a.ab.key2
```
V4 doesn't have a similar feature, however the fact that you can run multiple operations in a single expression makes it easier to come up with a shell script that does the same thing:
```bash
#!/bin/bash
yq e '
.a.key1 = "things" |
del(.a.ab.key2)
' ./examples/data1.yaml
```
### Some new things you can do in v4:
Construct dynamic yaml [maps ](broken-reference)and [arrays ](broken-reference)based on input yaml
Using the [union ](broken-reference)operator, you can run multiple updates in one go and read multiple paths in one go
Fine grain merging of maps using the [multiply](broken-reference) operator
Read and and control yaml metadata better (e.g. [tags](broken-reference), [paths](broken-reference), [document indexes](broken-reference), [anchors and aliases](broken-reference), [comments](broken-reference)).
Work with multiple files (not just for merge)
The underlying expression language is much more powerful than `v3` so expect to see more features soon!
###

97
usage/convert.md Normal file
View File

@ -0,0 +1,97 @@
# Working with JSON
## Yaml to Json
To convert output to json, use the `--output-format=json` (or `-o=j`) flag. You can change the json output format by using the [indent](output-format.md#indent) flag.&#x20;
Given a sample.yaml file of:
```yaml
b:
c: 2
```
then
```bash
yq eval -o=j sample.yaml
```
will output
```javascript
{
"b": {
"c": 2
}
}
```
To format the json:
```yaml
yq eval -o=j -I=0 sample.yaml
```
will yield
```yaml
{"b":{"c":2}}
```
### Multiple matches
Each matching yaml node will be converted to json and printed out as a separate json doc. You may want to set the [indent](output-format.md#indent) flags to 0 if you want a json doc per line.
Given a sample.yaml file of:
```yaml
bob:
c: 2
bab:
c: 5
```
then
```bash
yq eval -o=j '.b*' sample.yaml
```
will output
```javascript
{
"c": 2
}
{
"c": 5
}
```
## Json to Yaml
To read in json, just pass in a json file instead of yaml, it will just work - as json is a subset of yaml. However, you will probably want to use the [Style Operator](broken-reference) or `--prettyPrint/-P` flag to make look more like an idiomatic yaml document. This can be done by resetting the style of all elements.
e.g given a json file
```javascript
{"a":"Easy! as one two three","b":{"c":2,"d":[3,4]}}
```
then
```bash
yq eval -P sample.json
```
will output
```yaml
a: Easy! as one two three
b:
c: 2
d:
- 3
- 4
```

50
usage/front-matter.md Normal file
View File

@ -0,0 +1,50 @@
# Front Matter
`yq` can process files with `yaml` front matter (e.g. jekyll, assemble and others) - this is done via the `--front-matter/-f` flag.
## Process front matter
Use `--front-matter=process` to process the front matter, that is run the expression against the `yaml` content, and output back the entire file, included the non-yaml content block. For example:
File:
```
---
a: apple
b: bannana
---
<h1>I like {{a}} and {{b}} </h1>
```
The running
```
yq e --front-matter=process '.a="chocolate"' file.jekyll
```
Will yield:
```
---
a: chocolate
b: bannana
---
<h1>I like {{a}} and {{b}} </h1>
```
## Extract front matter
Running with `--front-matter=extract` will only output the yaml contents and ignore the rest. From the previous example, if you were to instead run:
```
yq e --front-matter=extract '.a="chocolate"' file.jekyll
```
Then this would yield:
```
---
a: chocolate
b: bannana
```

29
usage/github-action.md Normal file
View File

@ -0,0 +1,29 @@
# GitHub Action
You can use `yq` in your GitHub action, for instance:
```yaml
- uses: actions/checkout@v2
- name: Get SDK Version from config
id: lookupSdkVersion
uses: mikefarah/yq@master
with:
cmd: yq eval '.renutil.version' 'config.yml'
- name: Restore Cache
id: restore-cache
uses: actions/cache@v2
with:
path: ../renpy
key: ${{ runner.os }}-sdk-${{ steps.lookupSdkVersion.outputs.result }}
restore-keys: |
${{ runner.os }}-sdk
# ... more
```
The `yq` action sets a `result` variable in its output, making it available to subsequent steps. In this case it's available as `steps.lookupSdkVersion.outputs.result`.
Details of how the GitHub action itself is configured can be found [here](https://github.com/mikefarah/yq/issues/844#issuecomment-856700574)
If you [enable step debug logging](https://docs.github.com/en/actions/managing-workflow-runs/enabling-debug-logging#enabling-step-debug-logging), you can see additional information about the exact command sent as well as the response returned within the GitHub Action logs.
Thanks @[**devorbitus**](https://github.com/devorbitus)**!**

102
usage/output-format.md Normal file
View File

@ -0,0 +1,102 @@
---
description: Flags to control yaml and json output format
---
# Output format
These flags are available for all `yq` commands.&#x20;
## Color
By default, `yq` prints with colours if it detects a terminal. You can manully this by using either
The `--colors/-C`flag to force print with colors.&#x20;
The \``--no-colors/-M` flag to force print without colours
## Pretty Print
To print out idiomatic `yaml` use the `--prettyPrint/-P` flag. Note that this is shorthand for using the [style](broken-reference) operator `... style=""`
## Indent
Use the indent flag `--indent/-I` to control the number of spaces used for indentation. This also works for JSON output. The default value is 2.&#x20;
Note that lists are indented at the same level as the map key at indent level 2, but are more deeply indented at indent level 4 and greater. This is (currently) a quirk of the underlying [yaml parser](https://github.com/go-yaml/yaml/tree/v3).
Given:
```
apples:
collection:
- name: Green
- name: Blue
favourite: Pink Lady
```
Then:
```
yq e -I4 sample.yaml
```
Will print out:
```yaml
apples:
collection:
- name: Green
- name: Blue
favourite: Pink Lady
```
This also works with json
```
yq e -j -I4 sample.yaml
```
yields
```javascript
{
"apples": {
"collection": [
{
"name": "Green"
},
{
"name": "Blue"
}
],
"favourite": "Pink Lady"
}
}
```
## Unwrap scalars
By default scalar values are 'unwrapped', that is only their value is printed (except when outputting as JSON). To print out the node as-is, with the original formatting an any comments pass in `--unwrapScalar=false`
Given data.yml:
```yaml
a: "Things" # cool stuff
```
Then:
`yq e --unwrapScalar=false '.a' data.yml`
Will yield:
```yaml
"Things" # cool stuff
```
where as without setting the flag to false you would get:
```yaml
Things
```

34
usage/properties.md Normal file
View File

@ -0,0 +1,34 @@
# Working with Properties
## Yaml to Properties
To convert to property file format, use `--outputformat=props` or `-o=p`. Porting the comments from the `yaml` file to the property file is still in progress, currently line comments on the node values will be copied across.&#x20;
Given a sample file of:
```yaml
# block comments don't come through
person: # neither do comments on maps
name: Mike # comments on values appear
pets:
- cat # comments on array values appear
food: [pizza] # comments on arrays do not
```
then
```bash
yq eval -o=p sample.yaml
```
will output:
```
# comments on values appear
person.name = Mike
# comments on array values appear
person.pets.0 = cat
person.food.0 = pizza
```

134
usage/tips-and-tricks.md Normal file
View File

@ -0,0 +1,134 @@
# 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:
```
yq e --exit-status 'tag == "!!map" or tag== "!!seq"' file.txt > /dev/null
```
## Split expressions over multiple lines to improve readablity
Feel free to use multiple lines in your expression to improve readability.
```bash
yq eval --inplace '
.a.b.c[0].frog = "thingo" |
.a.b.c[0].frog style= "double" |
.different.path.somehere = "foo" |
.different.path.somehere style= "folded"
' my_file.yaml
```
## Create bash array
Given a yaml file like
```yaml
coolActions:
- create
- edit
- delete
```
You can create a bash array named `actions` by:
```bash
> readarray actions < <(yq e '.coolActions[]' sample.yaml)
> echo "${actions[1]}"
edit
```
## Set contents from another file
Use an environment variable with the `strenv` operator to inject the contents from an environment variable.&#x20;
```bash
LICENSE=$(cat LICENSE) yq eval -n '.a = strenv(LICENSE)'
```
## Special characters in strings
The `strenv` operator is a great way to handle special characters in strings:
```bash
VAL='.a |!@ == "string2"' yq e '.a = strenv(VAL)' example.yaml
```
## Quotes in Windows Powershell
Powershell has its [own](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about\_quoting\_rules?view=powershell-7.1) way of handling quotes:
```bash
PS > yq e -n '.test = ""something""'
test: something
PS >
```
## 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.
```
yq ea '. as $item ireduce ({}; . * $item )' file1.yml file2.yml ...
```
## Creating a new file / working with blank documents
To create a new `yaml` file simply:
```
yq e -n '.someNew="content"' > newfile.yml
```
## 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:
```
diff <(yq e -P examples/data1.yaml) <(yq e -P examples/data2.yaml)
```
This way you can use the full power of `diff` and normalise the yaml files as you like - for instance 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:
```
yq e '.apple' <(curl -s https://somewhere/data1.yaml) <(cat file.yml)
```
## Updating deeply selected paths
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.
```
yq '(.foo.bar[] | select(name == "fred) | .apple) = "cool"'
```
## Combining multiple files into one
In order to combine multiple yaml files into a single file (with `---` separators) you can just:
```
yq e '.' somewhere/*.yaml
```
## &#x20;Multiple updates to the same path
You can use the [with](../operators/with.md) operator to set a nested context:
```
yq eval 'with(.a.deeply ; .nested = "newValue" | .other= "newThing")' sample.yml
```
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.