yq/pkg/yqlib/doc/Anchor and Alias Operators.md

Use the alias and anchor operators to read and write yaml aliases and anchors. The explode operator normalises a yaml file (dereference 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.

Get anchor

Given a sample.yml file of:

a: &billyBob cat
'': null

then

yq eval '.a | anchor' sample.yml

will output

billyBob

Set anchor

Given a sample.yml file of:

a: cat
'': null

then

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

will output

a: &foobar cat
'': null

Get alias

Given a sample.yml file of:

b: &billyBob meow
a: *billyBob
'': null

then

yq eval '.a | alias' sample.yml

will output

billyBob

Set alias

Given a sample.yml file of:

b: &meow purr
a: cat
'': null

then

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

will output

b: &meow purr
a: *meow
'': null

Explode alias and anchor

Given a sample.yml file of:

f: {a: &a cat, b: *a}
'': null

then

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

will output

f: {a: cat, b: cat}
'': null

Explode with no aliases or anchors

Given a sample.yml file of:

a: mike
'': null

then

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

will output

a: mike
'': null

Explode with alias keys

Given a sample.yml file of:

f: {a: &a cat, *a: b}
'': null

then

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

will output

f: {a: cat, cat: b}
'': null

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
'': null

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
  a: foo_a
  thing: bar_thing
  c: foobarList_c
foobar:
  c: foo_c
  a: foo_a
  thing: foobar_thing
'': null