yq: Anchors, Aliases, and the explode Operator
yq preserves YAML anchors and aliases through edits and can flatten them with the explode operator.
YAML anchors (&name) and aliases (*name) let configs share blocks. yq keeps them by default, but downstream tools sometimes need them inlined, which explode does.
What it does
An anchor &name marks a node; an alias *name reuses it; the merge key <<: *name merges an anchored map in. mikefarah/yq preserves these when editing. explode(.) inlines every alias and merge key into concrete values, producing a self-contained document.
Common usage
# inline all anchors/aliases into plain values
yq 'explode(.)' config.yaml
# explode then convert to JSON (JSON has no anchors)
yq -o=json 'explode(.)' config.yaml
# read a value that comes via a merge key
yq '.production.replicas' config.yamlAnchor syntax
| YAML / expression | Meaning |
|---|---|
| &name | Define an anchor on a node |
| *name | Alias: reuse the anchored node |
| <<: *name | Merge key: merge an anchored map |
| explode(.) | Inline all aliases and merge keys |
| ... comments="" | Often paired to clean exploded output |
In CI
Some tools (and JSON) cannot represent anchors; run yq -o=json 'explode(.)' to hand them a fully expanded document. When editing a file meant for humans, skip explode so the shared blocks and their anchors stay intact in the diff.
Common errors in CI
"Error: ... could not find anchor" means an alias references an anchor that was deleted or never defined; explode or fix the anchor. Converting anchored YAML to JSON without explode can drop or misrepresent the shared data, since JSON has no anchors. kislyuk/yq resolves anchors implicitly through its JSON round-trip but loses comments doing so, another behavior split from Go yq.