Anchor and Alias Operators

Search…
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.
Note that versions prior to 4.18 require the 'eval/e' command to be specified.
yq e <exp> <file>
Merge one map
see https://yaml.org/type/merge.html
Given a sample.yml file of:
1
- &CENTER
2
  x: 1
3
  y: 2
4
- &LEFT
5
  x: 0
6
  y: 2
7
- &BIG
8
  r: 10
9
- &SMALL
10
  r: 1
11
- !!merge <<: *CENTER
12
  r: 10
Copied!
then
1
yq '.[4] | explode(.)' sample.yml
Copied!
will output
1
x: 1
2
y: 2
3
r: 10
Copied!
Merge multiple maps
see https://yaml.org/type/merge.html
Given a sample.yml file of:
1
- &CENTER
2
  x: 1
3
  y: 2
4
- &LEFT
5
  x: 0
6
  y: 2
7
- &BIG
8
  r: 10
9
- &SMALL
10
  r: 1
11
- !!merge <<:
12
    - *CENTER
13
    - *BIG
Copied!
then
1
yq '.[4] | explode(.)' sample.yml
Copied!
will output
1
r: 10
2
x: 1
3
y: 2
Copied!
Override
see https://yaml.org/type/merge.html
Given a sample.yml file of:
1
- &CENTER
2
  x: 1
3
  y: 2
4
- &LEFT
5
  x: 0
6
  y: 2
7
- &BIG
8
  r: 10
9
- &SMALL
10
  r: 1
11
- !!merge <<:
12
    - *BIG
13
    - *LEFT
14
    - *SMALL
15
  x: 1
Copied!
then
1
yq '.[4] | explode(.)' sample.yml
Copied!
will output
1
r: 10
2
x: 1
3
y: 2
Copied!
Get anchor
Given a sample.yml file of:
1
a: &billyBob cat
Copied!
then
1
yq '.a | anchor' sample.yml
Copied!
will output
1
billyBob
Copied!
Set anchor
Given a sample.yml file of:
1
a: cat
Copied!
then
1
yq '.a anchor = "foobar"' sample.yml
Copied!
will output
1
a: &foobar cat
Copied!
Set anchor relatively using assign-update
Given a sample.yml file of:
1
a:
2
  b: cat
Copied!
then
1
yq '.a anchor |= .b' sample.yml
Copied!
will output
1
a: &cat
2
  b: cat
Copied!
Get alias
Given a sample.yml file of:
1
b: &billyBob meow
2
a: *billyBob
Copied!
then
1
yq '.a | alias' sample.yml
Copied!
will output
1
billyBob
Copied!
Set alias
Given a sample.yml file of:
1
b: &meow purr
2
a: cat
Copied!
then
1
yq '.a alias = "meow"' sample.yml
Copied!
will output
1
b: &meow purr
2
a: *meow
Copied!
Set alias to blank does nothing
Given a sample.yml file of:
1
b: &meow purr
2
a: cat
Copied!
then
1
yq '.a alias = ""' sample.yml
Copied!
will output
1
b: &meow purr
2
a: cat
Copied!
Set alias relatively using assign-update
Given a sample.yml file of:
1
b: &meow purr
2
a:
3
  f: meow
Copied!
then
1
yq '.a alias |= .f' sample.yml
Copied!
will output
1
b: &meow purr
2
a: *meow
Copied!
Explode alias and anchor
Given a sample.yml file of:
1
f:
2
  a: &a cat
3
  b: *a
Copied!
then
1
yq 'explode(.f)' sample.yml
Copied!
will output
1
f:
2
  a: cat
3
  b: cat
Copied!
Explode with no aliases or anchors
Given a sample.yml file of:
1
a: mike
Copied!
then
1
yq 'explode(.a)' sample.yml
Copied!
will output
1
a: mike
Copied!
Explode with alias keys
Given a sample.yml file of:
1
f:
2
  a: &a cat
3
  *a: b
Copied!
then
1
yq 'explode(.f)' sample.yml
Copied!
will output
1
f:
2
  a: cat
3
  cat: b
Copied!
Explode with merge anchors
Given a sample.yml file of:
1
foo: &foo
2
  a: foo_a
3
  thing: foo_thing
4
  c: foo_c
5
bar: &bar
6
  b: bar_b
7
  thing: bar_thing
8
  c: bar_c
9
foobarList:
10
  b: foobarList_b
11
  !!merge <<:
12
    - *foo
13
    - *bar
14
  c: foobarList_c
15
foobar:
16
  c: foobar_c
17
  !!merge <<: *foo
18
  thing: foobar_thing
Copied!
then
1
yq 'explode(.)' sample.yml
Copied!
will output
1
foo:
2
  a: foo_a
3
  thing: foo_thing
4
  c: foo_c
5
bar:
6
  b: bar_b
7
  thing: bar_thing
8
  c: bar_c
9
foobarList:
10
  b: bar_b
11
  thing: foo_thing
12
  c: foobarList_c
13
  a: foo_a
14
foobar:
15
  c: foo_c
16
  a: foo_a
17
  thing: foobar_thing
Copied!
Dereference and update a field
`Use explode with multiply to dereference an object
Given a sample.yml file of:
1
item_value: &item_value
2
  value: true
3
thingOne:
4
  name: item_1
5
  !!merge <<: *item_value
6
thingTwo:
7
  name: item_2
8
  !!merge <<: *item_value
Copied!
then
1
yq '.thingOne |= explode(.) * {"value": false}' sample.yml
Copied!
will output
1
item_value: &item_value
2
  value: true
3
thingOne:
4
  name: item_1
5
  value: false
6
thingTwo:
7
  name: item_2
8
  !!merge <<: *item_value
Copied!