Skip to content

Commit 84b095b

Browse files
mikefarahmikefarah
committed
Making examples of the merge fix flag clearer
1 parent f35e57d commit 84b095b

8 files changed

+67
-34
lines changed

‎pkg/yqlib/doc/operators/anchor-and-alias-operators.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,14 @@ Use the `alias` and `anchor` operators to read and write yaml aliases and anchor
55
`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.
66

77

8+
## NOTE --yaml-fix-merge-anchor-to-spec flag
9+
`yq` doesn't merge anchors `<<:` to spec, in some circumstances it incorrectly overrides existing keys when the spec documents not to do that.
10+
11+
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)
12+
13+
See examples of the flag difference below.
14+
15+
816
## Merge one map
917
see https://yaml.org/type/merge.html
1018

@@ -285,7 +293,7 @@ thingTwo:
285293
```
286294

287295
## LEGACY: Explode with merge anchors
288-
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. Flag will default to true in late 2025
296+
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
289297

290298
Given a sample.yml file of:
291299
```yaml
@@ -334,7 +342,7 @@ foobar:
334342
```
335343
336344
## FIXED: Explode with merge anchors
337-
Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Flag will default to true in late 2025
345+
See the foobarList.b property is still foobarList_b. Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Flag will default to true in late 2025
338346

339347
Given a sample.yml file of:
340348
```yaml
@@ -383,7 +391,7 @@ foobar:
383391
```
384392

385393
## FIXED: Explode with merge anchors
386-
Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Flag will default to true in late 2025
394+
See the foobarList.b property is still foobarList_b. Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Flag will default to true in late 2025
387395

388396
Given a sample.yml file of:
389397
```yaml

‎pkg/yqlib/doc/operators/headers/anchor-and-alias-operators.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,11 @@ Use the `alias` and `anchor` operators to read and write yaml aliases and anchor
44

55
`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.
66

7+
8+
## NOTE --yaml-fix-merge-anchor-to-spec flag
9+
`yq` doesn't merge anchors `<<:` to spec, in some circumstances it incorrectly overrides existing keys when the spec documents not to do that.
10+
11+
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)
12+
13+
See examples of the flag difference below.
14+

‎pkg/yqlib/doc/operators/headers/traverse-read.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
11
# Traverse (Read)
22

33
This is the simplest (and perhaps most used) operator. It is used to navigate deeply into yaml structures.
4+
5+
6+
## NOTE --yaml-fix-merge-anchor-to-spec flag
7+
`yq` doesn't merge anchors `<<:` to spec, in some circumstances it incorrectly overrides existing keys when the spec documents not to do that.
8+
9+
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)
10+
11+
See examples of the flag differences below.
12+

‎pkg/yqlib/doc/operators/traverse-read.md

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@
22

33
This is the simplest (and perhaps most used) operator. It is used to navigate deeply into yaml structures.
44

5+
6+
## NOTE --yaml-fix-merge-anchor-to-spec flag
7+
`yq` doesn't merge anchors `<<:` to spec, in some circumstances it incorrectly overrides existing keys when the spec documents not to do that.
8+
9+
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)
10+
11+
See examples of the flag differences below.
12+
13+
514
## Simple map navigation
615
Given a sample.yml file of:
716
```yaml
@@ -352,7 +361,7 @@ a
352361
c
353362
```
354363

355-
## Traversing merge anchors with override
364+
## LEGACY: Traversing merge anchors with override
356365
This is legacy behaviour, see --yaml-fix-merge-anchor-to-spec
357366

358367
Given a sample.yml file of:
@@ -385,7 +394,7 @@ will output
385394
foo_c
386395
```
387396

388-
## Traversing merge anchor lists
397+
## LEGACY: Traversing merge anchor lists
389398
Note that the later merge anchors override previous, but this is legacy behaviour, see --yaml-fix-merge-anchor-to-spec
390399

391400
Given a sample.yml file of:
@@ -418,7 +427,7 @@ will output
418427
bar_thing
419428
```
420429

421-
## Splatting merge anchors
430+
## LEGACY: Splatting merge anchors
422431
With legacy override behaviour, see --yaml-fix-merge-anchor-to-spec
423432

424433
Given a sample.yml file of:
@@ -453,7 +462,7 @@ foo_a
453462
foobar_thing
454463
```
455464

456-
## Splatting merge anchor lists
465+
## LEGACY: Splatting merge anchor lists
457466
With legacy override behaviour, see --yaml-fix-merge-anchor-to-spec
458467

459468
Given a sample.yml file of:

‎pkg/yqlib/operator_anchors_aliases.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ func reconstructAliasedMap(node *CandidateNode, context Context) error {
162162
}
163163
}
164164
} else if showMergeAnchorToSpecWarning {
165-
log.Warning("--yaml-fix-merge-anchor-to-spec is false; causing merge anchors to override the existing values which isn't to the yaml spec. This flag will default to true in late 2025.")
165+
log.Warning("--yaml-fix-merge-anchor-to-spec is false; causing merge anchors to override the existing values which isn't to the yaml spec. This flag will default to true in late 2025. See https://mikefarah.gitbook.io/yq/operators/anchor-and-alias-operators for more details.")
166166
showMergeAnchorToSpecWarning = false
167167
}
168168

‎pkg/yqlib/operator_anchors_aliases_test.go

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -104,14 +104,14 @@ var fixedAnchorOperatorScenarios = []expressionScenario{
104104
{
105105
skipDoc: true,
106106
description: "merge anchor after existing keys",
107-
subdescription: "Does not override existing keys",
107+
subdescription: "Does not override existing keys - note the name field in the second element is still ellipse.",
108108
document: explodeWhenKeysExistDocument,
109109
expression: "explode(.)",
110110
expected: []string{explodeWhenKeysExistExpected},
111111
},
112112
{
113113
description: "FIXED: Explode with merge anchors",
114-
subdescription: "Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Flag will default to true in late 2025 ",
114+
subdescription: "See the foobarList.b property is still foobarList_b. Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Flag will default to true in late 2025 ",
115115
document: mergeDocSample,
116116
expression: `explode(.)`,
117117
expected: []string{explodeMergeAnchorsFixedExpected},
@@ -148,7 +148,7 @@ var badAnchorOperatorScenarios = []expressionScenario{
148148
},
149149
{
150150
description: "LEGACY: Explode with merge anchors", // incorrect overrides
151-
subdescription: "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. Flag will default to true in late 2025",
151+
subdescription: "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",
152152
document: mergeDocSample,
153153
expression: `explode(.)`,
154154
expected: []string{explodeMergeAnchorsExpected},

‎pkg/yqlib/operator_traverse_path.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -295,7 +295,7 @@ func doTraverseMap(newMatches *orderedmap.OrderedMap, node *CandidateNode, wante
295295
if !ConfiguredYamlPreferences.FixMergeAnchorToSpec {
296296
log.Debug("Merge anchor")
297297
if showMergeAnchorToSpecWarning {
298-
log.Warning("--yaml-fix-merge-anchor-to-spec is false; causing merge anchors to override the existing values which isn't to the yaml spec. This flag will default to true in late 2025.")
298+
log.Warning("--yaml-fix-merge-anchor-to-spec is false; causing merge anchors to override the existing values which isn't to the yaml spec. This flag will default to true in late 2025. See https://mikefarah.gitbook.io/yq/operators/traverse-read for more details.")
299299
showMergeAnchorToSpecWarning = false
300300
}
301301
err := traverseMergeAnchor(newMatches, value, wantedKey, prefs, splat)

‎pkg/yqlib/operator_traverse_path_test.go

Lines changed: 21 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -27,40 +27,39 @@ foobar:
2727

2828
var fixedTraversePathOperatorScenarios = []expressionScenario{
2929
{
30-
skipDoc: true,
31-
description: "Traversing merge anchor lists",
32-
subdescription: "Note that the keys earlier in the merge anchors sequence override later ones",
30+
description: "FIXED: Traversing merge anchors with override",
31+
subdescription: "Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour.",
3332
document: mergeDocSample,
34-
expression: `.foobarList.thing`,
33+
expression: `.foobar.c`,
3534
expected: []string{
36-
"D0, P[foo thing], (!!str)::foo_thing\n",
35+
"D0, P[foobar c], (!!str)::foobar_c\n",
3736
},
3837
},
3938
{
40-
skipDoc: true,
41-
description: "Traversing merge anchors with override",
42-
document: mergeDocSample,
43-
expression: `.foobar.c`,
39+
description: "FIXED: Traversing merge anchor lists",
40+
subdescription: "Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Note that the keys earlier in the merge anchors sequence override later ones",
41+
document: mergeDocSample,
42+
expression: `.foobarList.thing`,
4443
expected: []string{
45-
"D0, P[foobar c], (!!str)::foobar_c\n",
44+
"D0, P[foo thing], (!!str)::foo_thing\n",
4645
},
4746
},
4847
{
49-
skipDoc: true,
50-
description: "Splatting merge anchors",
51-
document: mergeDocSample,
52-
expression: `.foobar[]`,
48+
description: "FIXED: Splatting merge anchors",
49+
subdescription: "Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Note that the keys earlier in the merge anchors sequence override later ones",
50+
document: mergeDocSample,
51+
expression: `.foobar[]`,
5352
expected: []string{
5453
"D0, P[foo a], (!!str)::foo_a\n",
5554
"D0, P[foobar thing], (!!str)::foobar_thing\n",
5655
"D0, P[foobar c], (!!str)::foobar_c\n",
5756
},
5857
},
5958
{
60-
skipDoc: true,
61-
description: "Splatting merge anchor lists",
62-
document: mergeDocSample,
63-
expression: `.foobarList[]`,
59+
description: "FIXED: Splatting merge anchor lists",
60+
subdescription: "Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Note that the keys earlier in the merge anchors sequence override later ones",
61+
document: mergeDocSample,
62+
expression: `.foobarList[]`,
6463
expected: []string{
6564
"D0, P[foobarList b], (!!str)::foobarList_b\n",
6665
"D0, P[foo thing], (!!str)::foo_thing\n",
@@ -80,7 +79,7 @@ var fixedTraversePathOperatorScenarios = []expressionScenario{
8079

8180
var badTraversePathOperatorScenarios = []expressionScenario{
8281
{
83-
description: "Traversing merge anchors with override",
82+
description: "LEGACY: Traversing merge anchors with override",
8483
subdescription: "This is legacy behaviour, see --yaml-fix-merge-anchor-to-spec",
8584
document: mergeDocSample,
8685
expression: `.foobar.c`,
@@ -89,7 +88,7 @@ var badTraversePathOperatorScenarios = []expressionScenario{
8988
},
9089
},
9190
{
92-
description: "Traversing merge anchor lists",
91+
description: "LEGACY: Traversing merge anchor lists",
9392
subdescription: "Note that the later merge anchors override previous, " +
9493
"but this is legacy behaviour, see --yaml-fix-merge-anchor-to-spec",
9594
document: mergeDocSample,
@@ -99,7 +98,7 @@ var badTraversePathOperatorScenarios = []expressionScenario{
9998
},
10099
},
101100
{
102-
description: "Splatting merge anchors",
101+
description: "LEGACY: Splatting merge anchors",
103102
subdescription: "With legacy override behaviour, see --yaml-fix-merge-anchor-to-spec",
104103
document: mergeDocSample,
105104
expression: `.foobar[]`,
@@ -110,7 +109,7 @@ var badTraversePathOperatorScenarios = []expressionScenario{
110109
},
111110
},
112111
{
113-
description: "Splatting merge anchor lists",
112+
description: "LEGACY: Splatting merge anchor lists",
114113
subdescription: "With legacy override behaviour, see --yaml-fix-merge-anchor-to-spec",
115114
document: mergeDocSample,
116115
expression: `.foobarList[]`,

0 commit comments

Comments
 (0)