taigrr/yq
1
0
Fork 0
mirror of https://github.com/taigrr/yq synced 2025-01-18 04:53:17 -08:00
Code Issues Projects Releases Wiki Activity

GitBook: [v3.x] 17 pages modified

Browse Source
This commit is contained in:
Mike Farah
2020-06-16 01:19:04 +00:00
committed by gitbook-bot
parent 086f0ec6b9
commit 85bb1aec16
17 changed files with 2347 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
commands/compare.md Normal file
View File

@@ -0,0 +1,103 @@
---
description: Deeply compare two yaml documents
---
# Compare
```bash
yq compare <yaml_file_1> <yaml_file_2> <path_expression>
```
Compares the matching yaml nodes at path expression in the two yaml documents. See [path expression](../usage/path-expressions.md) for more details. Difference calculated line by line, and is printed out line by line where the first character of each line is either:
* `` a space, indicating no change at this line
* `-` a minus ,indicating the line is not present in the second document \(it's removed\)
* `+` a plus, indicating that the line is not present in the first document \(it's added\)
If there are differences then `yq` will print out the differences and exit with code 1. If there are no differences, then nothing will be printed and the exit code will be 0.
## Example data
Given data1.yaml
```yaml
"apples": are nice
somethingElse: cool # this is nice
favouriteNumbers: [1,2,3]
noDifference: it's the same
```
and data2.yaml
```yaml
apples: are nice
somethingElse: cool # yeah i like it
favouriteNumbers:
- 1
- 3
- 4
noDifference: it's the same
```
## Basic
Basic will compare the yaml documents 'as-is'
```yaml
yq compare data1.yaml data2.yaml
```
yields
```text
-"apples": are nice
-somethingElse: cool # this is nice
-favouriteNumbers: [1, 2, 3]
+apples: are nice
+somethingElse: cool # yeah i like it
+favouriteNumbers:
+- 1
+- 3
+- 4
noDifference: it's the same
```
## Formatted
Most of the time, it will make sense to [format](../usage/output-format.md#pretty-print) the documents before comparing:
```text
yq compare --prettyPrint data1.yaml data2.yml
```
yields
```text
apples: are nice
-somethingElse: cool # this is nice
+somethingElse: cool # yeah i like it
favouriteNumbers:
- 1
-- 2
- 3
+- 4
noDifference: it's the same
```
## Using path expressions
Use [path expressions](../usage/path-expressions.md) to compare subsets of yaml documents
```text
yq compare -P data1.yaml data2.yml favouriteNumbers
```
yields
```text
- 1
-- 2
- 3
+- 4
```

58
commands/create.md Normal file
View File

@@ -0,0 +1,58 @@
# Create
```text
yq n <path_expression> <new value>
```
This works in the same way as the write command, but you don't pass in an existing Yaml file. Currently this does not support creating multiple documents in a single yaml file.
See docs for [path expression](../usage/path-expressions.md) and [value parsing](../usage/value-parsing.md) for more details, including controlling quotes and tags.
## Creating a simple yaml file
```bash
yq n b.c cat
```
will output:
```yaml
b:
c: cat
```
## Creating using a create script
Create scripts follow the same format as the update scripts.
Given a script create\_instructions.yaml of:
```yaml
- command: update
path: b.c
value:
#great
things: frog # wow!
```
then
```bash
yq n -s create_instructions.yaml
```
will output:
```yaml
b:
c:
#great
things: frog # wow!
```
You can also pipe the instructions in:
```bash
cat create_instructions.yaml | yq n -s -
```

110
commands/delete.md Normal file
View File

@@ -0,0 +1,110 @@
---
description: Deletes all the matching nodes for the path expression in the given yaml input
---
# Delete
```text
yq delete <yaml_file|-> <path_expression>
```
See docs for [path expression](../usage/path-expressions.md) for more details.
## Deleting from a simple document
Given a sample.yaml file of:
```yaml
b:
c: 2
apples: green
```
then
```bash
yq d sample.yaml b.c
```
will output
```yaml
b:
apples: green
```
## From STDIN
Use "-" \(without quotes\) in-place of a file name if you wish to pipe in input from STDIN.
```bash
cat sample.yaml | yq d - b.c
```
## Deleting in-place
```bash
yq d -i sample.yaml b.c
```
will update the sample.yaml file so that the 'c' node is deleted
## Multiple Documents
### Delete from single document
Given a sample.yaml file of:
```yaml
something: else
field: leaveMe
---
b:
c: 2
field: deleteMe
```
then
```bash
yq w -d1 sample.yaml field
```
will output:
```yaml
something: else
field: leaveMe
---
b:
c: 2
```
### Delete from all documents
Given a sample.yaml file of:
```yaml
something: else
field: deleteMe
---
b:
c: 2
field: deleteMeToo
```
then
```bash
yq w -d'*' sample.yaml field
```
will output:
```yaml
something: else
---
b:
c: 2
```

232
commands/merge.md Normal file
View File

@@ -0,0 +1,232 @@
---
description: Merge multiple yaml files into a one
---
# Merge
Yaml files can be merged using the 'merge' command. Each additional file merged with the first file will set values for any key not existing already or where the key has no value.
```text
yq m <yaml_file> <yaml_file2> <yaml_file3>...
```
## Merge example
Given a data1.yaml file of:
```yaml
a: simple
b: [1, 2]
```
and data2.yaml file of:
```yaml
a: other
c:
test: 1
```
then
```bash
yq merge data1.yaml data2.yaml
```
will output:
```yaml
a: simple
b: [1, 2]
c:
test: 1
```
## Updating files in-place
```bash
yq m -i data1.yaml data2.yaml
```
will update the data1.yaml file with the merged result.
## Overwrite values
Given a data1.yaml file of:
```yaml
a: simple
b: [1, 2]
d: left alone
```
and data2.yaml file of:
```yaml
a: other
b: [3, 4]
c:
test: 1
```
then
```bash
yq m -x data1.yaml data2.yaml
```
will output:
```yaml
a: other
b: [3, 4]
c:
test: 1
d: left alone
```
Notice that 'b' does not result in the merging of the values within an array.
## Append values with arrays
Given a data1.yaml file of:
```yaml
a: simple
b: [1, 2]
d: hi
```
and data2.yaml file of:
```yaml
a: something
b: [3, 4]
c:
test: 2
other: true
```
then
```bash
yq m -a data1.yaml data2.yaml
```
will output:
```yaml
a: simple
b: [1, 2, 3, 4]
c:
test: 2
other: true
d: hi
```
Note that the 'b' array has concatenated the values from the second data file. Also note that other map keys are not overridden \(field a\).
## Auto-create
By default, `yq` will automatically create any missing entries in the target yaml file. This can be turned off so that only matching paths are merged in. When turned off - you will most likely want to use the [override flag](merge.md#overwrite-values).
Given a data1.yml file of:
```yaml
a: thing
b: something else
```
and data2.yml file of:
```yaml
b: new value
d: not in original
```
Then
```yaml
yq m --overwrite --autocreate=false data1.yml data2.yml
```
will yield
```yaml
a: thing
b: new value
```
## Multiple Documents
### Merge into single document
Currently yq only has multi-document support for the _first_ document being merged into. The remaining yaml files will have their first document selected.
Given a data1.yaml file of:
```yaml
something: else
---
a: simple
b: cat
```
and data3.yaml file of:
```yaml
b: dog
```
then
```bash
yq m -x -d1 data1.yaml data3.yaml
```
will output:
```yaml
something: else
---
a: simple
b: dog
```
### Merge into all documents
Currently yq only has multi-document support for the _first_ document being merged into. The remaining yaml files will have their first document selected.
Given a data1.yaml file of:
```yaml
something: else
---
a: simple
b: cat
```
and data3.yaml file of:
```yaml
b: dog
```
then
```bash
yq m -x -d'*' data1.yaml data3.yaml
```
will output:
```yaml
b: dog
something: else
---
a: simple
b: dog
```

103
commands/prefix.md Normal file
View File

@@ -0,0 +1,103 @@
---
description: >-
Prefixes a yaml document with the given path expression. The complete yaml
content will be nested inside the new prefix path.
---
# Prefix
```text
yq p <yaml_file> <path>
```
See docs for [path expression](../usage/path-expressions.md) for more details.
## Prefix a document
Given a data1.yaml file of:
```yaml
a:
b: [1, 2]
```
then
```bash
yq p data1.yaml c.d
```
will output:
```yaml
c:
d:
a:
b: [1, 2]
```
## Updating files in-place
```bash
yq p -i data1.yaml c
```
will update the data1.yaml file so that the path 'c' prefixes the document.
## Multiple Documents
### Prefix a single document
Given a data1.yaml file of:
```yaml
something: else
---
a: simple
b: cat
```
then
```bash
yq p -d1 data1.yaml c
```
will output:
```yaml
something: else
---
c:
a: simple
b: cat
```
### Prefix all documents
Given a data1.yaml file of:
```yaml
something: else
---
a: simple
b: cat
```
then
```bash
yq p -d'*' data1.yaml c
```
will output:
```yaml
c:
something: else
---
c:
a: simple
b: cat
```

326
commands/read.md Normal file
View File

@@ -0,0 +1,326 @@
---
description: Returns matching nodes/values of a path expression for a given yaml document
---
# Read
```text
yq r <yaml_file|json_file> <path_expression>
```
Returns the matching nodes of the path expression for the given yaml file \(or STDIN\).
See docs for [path expression](../usage/path-expressions.md) for more details.
## Basic
Given a sample.yaml file of:
```yaml
b:
c: 2
```
then
```bash
yq r sample.yaml b.c
```
will output the value of '2'.
## From Stdin
Given a sample.yaml file of:
```bash
cat sample.yaml | yq r - b.c
```
will output the value of '2'.
## Default values
Using the `--defaultValue/-D` flag you can specify a default value to be printed when no matching nodes are found for an expression
```text
yq r sample.yaml --defaultValue frog path.not.there
```
will yield \(assuming `path.not.there` does not match any nodes\):
```text
frog
```
## Printing matching paths
By default, yq will only print the value of the path expression for the yaml document. By specifying `--printMode` or `-p` you can print the matching paths.
```yaml
a:
thing_a:
animal: cat
other:
animal: frog
thing_b:
vehicle: car
```
### Path Only
```bash
yq r --printMode p "a.thing*.*"
```
will print
```text
a.thing_a.animal
a.thing_b.vehicle
```
### Path and Value
```bash
yq r --printMode pv "a.thing*.*"
```
will print
```text
a.thing_a.animal: cat
a.thing_b.vehicle: car
```
## Collect results into an array
By default, results are printed out line by line as independent matches. This is handy for both readability as well as piping into tools like `xargs`. However, if you would like to collect the matching results into an array then use the `--collect/-C` flag. This is particularly useful with the `length` flag described below.
Given:
```yaml
a:
thing_a:
animal: cat
other:
animal: frog
thing_b:
vehicle: car
```
```text
yq r sample.yaml --collect a.*.animal
```
will print
```text
- cat
- frog
```
## Printing length of the results
Use the `--length/-L` flag to print the length of results. For arrays this will be the number of items, objects the number of entries and scalars the length of the value.
Given
```text
animals:
- cats
- dog
- cheetah
```
```text
yq r sample.yml --length animals
```
will print
```text
3
```
### Length of filtered results
By default, filtered results are printed _independently_ so you will get the length of each result printed on a separate line:
```text
yq r sample.yaml --length --printMode pv 'animals.(.==c*)'
```
```text
animals.[0]: 4
animals.[2]: 7
```
However, you'll often want to know the count of the filtered results - use the `--collect` flag to collect the results in the array. The length will then return the size of the array.
```text
yq r sample.yaml --length --collect 'animals.(.==c*)'
```
```text
2
```
## Anchors and Aliases
The read command will print out the anchors of a document and can also traverse them.
Lets take a look at a simple example file:
```yaml
foo: &foo
a: 1
foobar: *foo
```
### Printing anchors
```bash
yq r sample.yml foo
```
will print out
```yaml
&foo
a: 1
```
Similarly,
```text
yq r sample.yml foobar
```
prints out
```yaml
*foo
```
### Traversing anchors
To traverse an anchor, we need to either explicitly reference merged in values:
```text
yq r sample.yml foobar.a
```
to get
```text
1
```
or we can use deep splat to get all the values
```bash
yq r sample.yml -p pv "foobar.**"
```
prints
```yaml
foobar.a: 1
```
The same methods work for the `<<: [*blah, *thing]`anchors.
### Exploding Anchors
By default anchors are not exploded \(or expanded/de-referenced\) for viewing, and the yaml is shown as-is. Use the `--explodeAnchors/-X` flag to show the anchor values.
Given sample.yml:
```yaml
foo: &foo
a: original
thing: coolasdf
thirsty: yep
bar: &bar
b: 2
thing: coconut
c: oldbar
foobarList:
<<: [*foo,*bar]
c: newbar
```
Then
```text
yq r -X sample.yml foobarList
```
yields
```text
c: newbar
b: 2
thing: coconut
a: original
thirsty: yep
```
Note that yq processes the merge anchor list in reverse order, to ensure that the last items in the list override the preceding.
## Multiple Documents
### Reading from a single document
Given a sample.yaml file of:
```yaml
something: else
---
b:
c: 2
```
then
```bash
yq r -d1 sample.yaml b.c
```
will output the value of '2'.
### Read from all documents
Reading all documents will return the result as an array. This can be converted to json using the '-j' flag if desired.
Given a sample.yaml file of:
```yaml
name: Fred
age: 22
---
name: Stella
age: 23
---
name: Android
age: 232
```
then
```bash
yq r -d'*' sample.yaml name
```
will output:
```text
Fred
Stella
Android
```

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

@@ -0,0 +1,51 @@
---
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
yq shell-completion
```
To configure your bash shell to load completions for each session add to your bashrc
```text
# ~/.bashrc or ~/.profile
. <(yq shell-completion)
```
### zsh
```bash
yq shell-completion --variation=zsh
```
The generated completion script should be put somewhere in your $fpath named \_yq
### fish
```bash
yq shell-completion --variation=fish
```
Save the output to a '.fish' file and add it to your completions directory.
### PowerShell
```bash
yq shell-completion --variation=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.

54
commands/validate.md Normal file
View File

@@ -0,0 +1,54 @@
---
description: Validate a given yaml file
---
# Validate
```text
yq v <yaml_file|->
```
Validates the given yaml file, does nothing if its valid, otherwise it will print errors to Stderr and exit with a non 0 exit code. This works like the [read command](read.md) - but does not take a path expression and does not print the yaml if it is valid.
## Basic - valid
```text
yq v valid.yaml
```
This will not print anything, and finish with a successful \(0\) exit code.
## Basic - invalid, from stdin
```text
echo '[1234' | yq v -
```
This will print the parsing error to stderr:
```bash
10:43:09 main [ERRO] yaml: line 1: did not find expected ',' or ']'
```
And return a error exit code \(1\)
## Multiple documents
Like other commands, by default the validate command will only run against the first document in the yaml file. Note that when running against other specific document indexes, _all previous documents will also be validated._
### Validating a single document
```bash
yq v -d1 multidoc.yml
```
This will validate both document 0 and document 1 \(but not document 2\)
### Validating all documents
```bash
yq v -d'*' multidoc.yml
```
This will validate all documents in the yaml file. Note that \* is quoted to avoid the CLI from processing the wildcard.

285
commands/write-update.md Normal file
View File

@@ -0,0 +1,285 @@
---
description: >-
Updates all the matching nodes of path expression in a yaml file to the
supplied value.
---
# Write
```bash
yq w <yaml_file> <path_expression> <new value>
```
See docs for [path expression](../usage/path-expressions.md) and [value parsing](../usage/value-parsing.md) for more details, including controlling quotes and tags.
## Basic
Given a sample.yaml file of:
```yaml
b:
c: 2
```
then
```bash
yq w sample.yaml b.c cat
```
will output:
```yaml
b:
c: cat
```
### Updating files in-place
```bash
yq w -i sample.yaml b.c cat
```
will update the sample.yaml file so that the value of 'c' is cat.
## From STDIN
```bash
cat sample.yaml | yq w - b.c blah
```
## Adding new fields
Any missing fields in the path will be created on the fly.
Given a sample.yaml file of:
```yaml
b:
c: 2
```
then
```bash
yq w sample.yaml b.d[+] "new thing"
```
will output:
```yaml
b:
c: cat
d:
- new thing
```
## Appending value to an array field
Given a sample.yaml file of:
```yaml
b:
c: 2
d:
- new thing
- foo thing
```
then
```bash
yq w sample.yaml "b.d[+]" "bar thing"
```
will output:
```yaml
b:
c: cat
d:
- new thing
- foo thing
- bar thing
```
Note that the path is in quotes to avoid the square brackets being interpreted by your shell.
## Multiple Documents
### Update a single document
Given a sample.yaml file of:
```yaml
something: else
---
b:
c: 2
```
then
```bash
yq w -d1 sample.yaml b.c 5
```
will output:
```yaml
something: else
---
b:
c: 5
```
### Update all documents
Given a sample.yaml file of:
```yaml
something: else
---
b:
c: 2
```
then
```bash
yq w -d'*' sample.yaml b.c 5
```
will output:
```yaml
something: else
b:
c: 5
---
b:
c: 5
```
## Writing Anchors
The `---anchorName` flag can be used to set the anchor name of a node
Given a sample document of:
```yaml
commonStuff:
flavour: vanilla
```
Then:
```bash
yq write sample.yaml commonStuff --anchorName=commonBits
```
Will yield
```yaml
commonStuff: &commonBits
flavour: vanilla
```
## Writing Aliases
The `--makeAlias` flag can create \(or update\) a node to be an alias to an anchor.
Given a sample file of:
```yaml
commonStuff: &commonBits
flavour: vanilla
```
Then
```bash
yq write sample.yaml --makeAnchor foo commonBits
```
Will yield:
```yaml
commonStuff: &commonBits
flavour: vanilla
foo: *commonBits
```
## Updating only styles/tags without affecting values
You can use the write command to update the quoting style of nodes, or their tags, without re-specifying the values. This is done by omitting the value argument:
Given a sample document:
```yaml
a:
c: things
d: other things
```
Then
```bash
yq write sample.yaml --style=single a.*
```
Will yield:
```yaml
a:
c: 'things'
d: 'other things'
```
## Using a script file to update
Given a sample.yaml file of:
```yaml
b:
d: be gone
c: 2
e:
- name: Billy Bob # comment over here
```
and a script update\_instructions.yaml of:
```yaml
- command: update
path: b.c
value:
#great
things: frog # wow!
- command: delete
path: b.d
```
then
```bash
yq w -s update_instructions.yaml sample.yaml
```
will output:
```yaml
b:
c:
#great
things: frog # wow!
e:
- name: Billy Bob # comment over here
```
And, of course, you can pipe the instructions in using '-':
```bash
cat update_instructions.yaml | yq w -s - sample.yaml
```