Anchor and Alias Operators
Last updated
Was this helpful?
Last updated
Was this helpful?
Was this helpful?
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.
yq
doesn't merge anchors <<:
to spec, in some circumstances it incorrectly overrides existing keys when the spec documents not to do that.
To minimise disruption while still fixing the issue, a flag has been added to toggle this behaviour. This will first default to false; and log warnings to users. Then it will default to true (and still allow users to specify false if needed).
This flag also enables advanced merging, like inline maps, as well as fixes to ensure when exploding a particular path, neighbours are not affect ed.
Long story short, you should be setting this flag to true.
See examples of the flag differences below, where LEGACY is with the flag off; and FIXED is with the flag on.
see https://yaml.org/type/merge.html
Given a sample.yml file of:
- &CENTER
x: 1
y: 2
- &LEFT
x: 0
y: 2
- &BIG
then
yq '.[4] | explode(.)' sample.yml
will output
x: 1
y: 2
r: 10
Given a sample.yml file of:
a: &billyBob cat
then
yq '.a | anchor' sample.yml
will output
billyBob
Given a sample.yml file of:
a: cat
then
yq '.a anchor = "foobar"' sample.yml
will output
a: &foobar cat
Given a sample.yml file of:
a:
b: cat
then
yq '.a anchor |= .b' sample.yml
will output
a: &cat
b: cat
Given a sample.yml file of:
b: &billyBob meow
a: *billyBob
then
yq '.a | alias' sample.yml
will output
billyBob
Given a sample.yml file of:
b: &meow purr
a: cat
then
yq '.a alias = "meow"' sample.yml
will output
b: &meow purr
a: *meow
Given a sample.yml file of:
b: &meow purr
a: cat
then
yq '.a alias = ""' sample.yml
will output
b: &meow purr
a: cat
Given a sample.yml file of:
b: &meow purr
a:
f: meow
then
yq '.a alias |= .f' sample.yml
will output
b: &meow purr
a: *meow
Given a sample.yml file of:
f:
a: &a cat
b: *a
then
yq 'explode(.f)' sample.yml
will output
f:
a: cat
b: cat
Given a sample.yml file of:
a: mike
then
yq 'explode(.a)' sample.yml
will output
a: mike
Given a sample.yml file of:
f:
a: &a cat
*a: b
then
yq 'explode(.f)' sample.yml
will output
f:
a: cat
cat: b
Use explode with multiply to dereference an object
Given a sample.yml file of:
item_value: &item_value
value: true
thingOne:
name: item_1
!!merge <<: *item_value
thingTwo:
name: item_2
!!merge <<: *item_value
then
yq '.thingOne |= (explode(.) | sort_keys(.)) * {"value": false}' sample.yml
will output
item_value: &item_value
value: true
thingOne:
name: item_1
value: false
thingTwo:
name: item_2
!!merge <<: *item_value
Caution: this is for when --yaml-fix-merge-anchor-to-spec=false; it's not to YAML spec because the merge anchors incorrectly override the object values (foobarList.b is set to bar_b when it should still be foobarList_b). Flag will default to true in late 2025
Given a sample.yml file of:
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
yq 'explode(.)' sample.yml
will output
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
see https://yaml.org/type/merge.html. This has the correct data, but the wrong key order; set --yaml-fix-merge-anchor-to-spec=true to fix the key order.
Given a sample.yml file of:
- &CENTER
x: 1
y: 2
- &LEFT
x: 0
y: 2
- &BIG
r: 10
- &SMALL
r: 1
- !!merge <<:
- *CENTER
- *BIG
then
yq '.[4] | explode(.)' sample.yml
will output
r: 10
x: 1
y: 2
see https://yaml.org/type/merge.html. This has the correct data, but the wrong key order; set --yaml-fix-merge-anchor-to-spec=true to fix the key order.
Given a sample.yml file of:
- &CENTER
x: 1
y: 2
- &LEFT
x: 0
y: 2
- &BIG
r: 10
- &SMALL
r: 1
- !!merge <<:
- *BIG
- *LEFT
- *SMALL
x: 1
then
yq '.[4] | explode(.)' sample.yml
will output
r: 10
x: 1
y: 2
Set --yaml-fix-merge-anchor-to-spec=true
to get this correct merge behaviour (flag will default to true in late 2025). Observe that foobarList.b property is still foobarList_b.
Given a sample.yml file of:
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
yq 'explode(.)' sample.yml
will output
foo:
a: foo_a
thing: foo_thing
c: foo_c
bar:
b: bar_b
thing: bar_thing
c: bar_c
foobarList:
b: foobarList_b
a: foo_a
thing: foo_thing
c: foobarList_c
foobar:
c: foobar_c
a: foo_a
thing: foobar_thing
Set --yaml-fix-merge-anchor-to-spec=true
to get this correct merge behaviour (flag will default to true in late 2025). Taken from https://yaml.org/type/merge.html. Same values as legacy, but with the correct key order.
Given a sample.yml file of:
- &CENTER
x: 1
y: 2
- &LEFT
x: 0
y: 2
- &BIG
r: 10
- &SMALL
r: 1
- !!merge <<:
- *CENTER
- *BIG
then
yq '.[4] | explode(.)' sample.yml
will output
x: 1
y: 2
r: 10
Set --yaml-fix-merge-anchor-to-spec=true
to get this correct merge behaviour (flag will default to true in late 2025). Taken from https://yaml.org/type/merge.html. Same values as legacy, but with the correct key order.
Given a sample.yml file of:
- &CENTER
x: 1
y: 2
- &LEFT
x: 0
y: 2
- &BIG
r: 10
- &SMALL
r: 1
- !!merge <<:
- *BIG
- *LEFT
- *SMALL
x: 1
then
yq '.[4] | explode(.)' sample.yml
will output
r: 10
y: 2
x: 1
Set --yaml-fix-merge-anchor-to-spec=true
to get this correct merge behaviour (flag will default to true in late 2025).
Given a sample.yml file of:
a:
b: &b 42
!!merge <<:
c: *b
then
yq 'explode(.) | sort_keys(.)' sample.yml
will output
a:
b: 42
c: 42