mirror of
https://github.com/taigrr/yq
synced 2025-01-18 04:53:17 -08:00
108 lines
2.3 KiB
Markdown
108 lines
2.3 KiB
Markdown
---
|
|
description: New features and breaking changes
|
|
---
|
|
|
|
# Upgrading from V2
|
|
|
|
## New Features
|
|
|
|
* Keeps yaml comments and formatting, can specify yaml [tags](usage/value-parsing.md#using-the-tag-field-to-override) when updating.
|
|
* Handles anchors!
|
|
* Can print out matching paths and values when splatting, more info [here](commands/read.md#printing-matching-paths).
|
|
* JSON output works for all commands! Yaml files with multiple documents are printed out as one JSON document per line, more info [here](usage/convert.md)
|
|
* Deep splat \(`**`\) to match arbitrary paths and match nodes by their children, more info [here](usage/path-expressions.md)
|
|
|
|
## Breaking Changes
|
|
|
|
### Parsing values from the CLI
|
|
|
|
In V3 users are able to better control how values are treated when updating YAML by using a new `--tag` argument \(see more info [here](usage/value-parsing.md)\). A result of this however, is that quoting values, e.g. "true" will no longer have an effect on how the value is interpreted like it did in V2.
|
|
|
|
For instance, to get the _string_ "true" into a yaml file:
|
|
|
|
V2:
|
|
|
|
```text
|
|
yq n a.path '"true"'
|
|
```
|
|
|
|
V3
|
|
|
|
```text
|
|
yq n a.path --tag '!!str' true
|
|
```
|
|
|
|
### Reading paths that don't exist
|
|
|
|
In V2 this would return null, V3 does not return anything.
|
|
|
|
Similarly, reading null yaml values `null`, `~` and , V2 returns null whereas V3 returns the values as is.
|
|
|
|
This is a result of taking effort not to format values coming in and out of the original YAML.
|
|
|
|
|
|
|
|
### Update scripts file format has changed to be more powerful.
|
|
|
|
Comments can be added, and delete commands have been introduced.
|
|
|
|
V2
|
|
|
|
```text
|
|
b.e[+].name: Mike Farah
|
|
```
|
|
|
|
V3
|
|
|
|
```yaml
|
|
- command: update
|
|
path: b.e[+].thing
|
|
value:
|
|
#great
|
|
things: frog # wow!
|
|
- command: delete
|
|
path: b.d
|
|
```
|
|
|
|
### Reading and splatting, matching results are printed once per line.
|
|
|
|
e.g:
|
|
|
|
```yaml
|
|
parent:
|
|
childA:
|
|
no: matches here
|
|
childB:
|
|
there: matches
|
|
hi: no match
|
|
there2: also matches
|
|
```
|
|
|
|
```text
|
|
yq r sample.yaml 'parent.*.there*'
|
|
```
|
|
|
|
V2
|
|
|
|
```text
|
|
- null
|
|
- - matches
|
|
- also matches
|
|
```
|
|
|
|
V3
|
|
|
|
```text
|
|
matches
|
|
also matches
|
|
```
|
|
|
|
### Converting JSON to YAML
|
|
|
|
As JSON is a subset of YAML, and `yq` now preserves the formatting of the passed in document, you will most likely need to use the `--prettyPrint` flag to format the JSON document as idiomatic YAML. See [Working with JSON](usage/convert.md#json-to-yaml) for more info.
|
|
|
|
|
|
|
|
|
|
|