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

Given a sample.yml file of:

- &CENTER
x: 1
y: 2
- &LEFT
x: 0
y: 2
- &BIG
r: 10
- &SMALL
r: 1
- !!merge <<: *CENTER
r: 10

then

yq eval '.[4] | explode(.)' sample.yml

will output

x: 1
y: 2
r: 10

Merge multiple maps

see https://yaml.org/type/merge.html

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 eval '.[4] | explode(.)' sample.yml

will output

r: 10
x: 1
y: 2

Override

see https://yaml.org/type/merge.html

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 eval '.[4] | explode(.)' sample.yml

will output

r: 10
x: 1
y: 2

Get anchor

Given a sample.yml file of:

a: &billyBob cat

then

yq eval '.a | anchor' sample.yml

will output

billyBob

Set anchor

Given a sample.yml file of:

a: cat

then

yq eval '.a anchor = "foobar"' sample.yml

will output

a: &foobar cat

Set anchor relatively using assign-update

Given a sample.yml file of:

a:
b: cat

then

yq eval '.a anchor |= .b' sample.yml

will output

a: &cat
b: cat

Get alias

Given a sample.yml file of:

b: &billyBob meow
a: *billyBob

then

yq eval '.a | alias' sample.yml

will output

billyBob

Set alias

Given a sample.yml file of:

b: &meow purr
a: cat

then

yq eval '.a alias = "meow"' sample.yml

will output

b: &meow purr
a: *meow

Set alias relatively using assign-update

Given a sample.yml file of:

b: &meow purr
a:
f: meow

then

yq eval '.a alias |= .f' sample.yml

will output

b: &meow purr
a: *meow

Explode alias and anchor

Given a sample.yml file of:

f:
a: &a cat
b: *a

then

yq eval 'explode(.f)' sample.yml

will output

f:
a: cat
b: cat

Explode with no aliases or anchors

Given a sample.yml file of:

a: mike

then

yq eval 'explode(.a)' sample.yml

will output

a: mike

Explode with alias keys

Given a sample.yml file of:

f:
a: &a cat
*a: b

then

yq eval 'explode(.f)' sample.yml

will output

f:
a: cat
cat: b

Explode with merge anchors

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 eval '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