anchors¶
What this rule does¶
Reports problems with YAML anchors and aliases — duplicated anchor
names, aliases that reference undeclared anchors, anchors that are declared
but never used, and (optionally) anchor/alias names that are ambiguous because
a : is welded to them. Projects can also forbid aliases alone or all anchors
and aliases.
Why this matters¶
- Forward references fail at runtime. An alias that points at an anchor declared later in the document is rejected by most YAML parsers.
- Duplicates are silently ambiguous. When two
&namedeclarations share a name, downstream consumers may bind to either one depending on parser order. - Unused anchors clutter intent. Removing dead anchors keeps the document's data-sharing structure explicit.
- A
:in a name means different things to different parsers. YAML 1.2.2 §6.9.2 lets an anchor/alias name contain any non-space character except the flow indicators,[]{}, so:is a legal name character. But parsers disagree where the name ends: ryl's parser, the YAML reference parser, andruamel.yamlread&foo:/*foo:as the namefoo:(colon included), while PyYAML/libyaml stop at the:(namefoo, colon treated as a mapping separator). So a document ofa: &foo: 42thenm:/- *foo:resolves to{a: 42, m: [42]}underruamel.yamlbut raises a parse error under PyYAML — the same bytes, two different meanings. A single space disambiguates (*foo : baris read the same way everywhere), so that is the form to use when an alias is genuinely a mapping key. Because ryl follows the spec here, the undeclared/duplicated/unused checks can differ from yamllint on colon-containing names; see How ryl differs from yamllint.
Configuration¶
[lint.rules.anchors]
level = "error"
forbid-undeclared-aliases = true
forbid-duplicated-anchors = false
forbid-unused-anchors = false
forbid-ambiguous-anchor-alias-names = false # ryl-only
forbid-anchors-and-aliases = false # ryl-only
forbid-aliases = false # ryl-only
| Option | Default | Description |
|---|---|---|
forbid-undeclared-aliases |
true |
Report aliases (*name) whose anchor (&name) has not been declared earlier. |
forbid-duplicated-anchors |
false |
Report when the same anchor name is declared more than once. |
forbid-unused-anchors |
false |
Report anchors that are never referenced by an alias. |
forbid-anchors-and-aliases |
false |
ryl-only. Report every anchor and alias, including valid declared-and-used pairs and aliases in merge keys (<<: *name). |
forbid-aliases |
false |
ryl-only. Report every alias (*name), including aliases in merge keys (<<: *name), while allowing anchors. |
forbid-ambiguous-anchor-alias-names |
false |
ryl-only. Report an anchor (&name) or alias (*name) whose name has a : welded to it — trailing (&foo:), internal (&foo:bar), or leading (&:foo) — the construct parsers disagree on. A space before the : (*foo : bar) is the unambiguous alias-key form and is never flagged. |
forbid-ambiguous-anchor-alias-names, forbid-anchors-and-aliases and
forbid-aliases are configurable only in TOML; YAML config rejects all three options.
All anchors options are independent. No option suppresses or overrides another.
With forbid-anchors-and-aliases and forbid-undeclared-aliases enabled,
an undeclared *missing receives two diagnostics. The duplicated, unused and
ambiguous name checks also report their matching conditions when enabled.
When both forbid-aliases and forbid-anchors-and-aliases are enabled, each alias
receives one forbidden-alias diagnostic: both options forbid the same condition.
forbid-unused-anchors can still report unreferenced anchors with either ban enabled.
Examples¶
Allowed¶
Reported (with forbid-undeclared-aliases: true)¶
Reported (with forbid-aliases = true)¶
Both aliases below are reported; the anchors, including &unused, are allowed:
Reported (with forbid-anchors-and-aliases = true)¶
Every & anchor and * alias below is reported, including the merge alias:
Allowed (with forbid-anchors-and-aliases = true)¶
Anchor-like text inside scalar values and comments is allowed:
job:
retries: 3
description: "Use &defaults and *defaults"
script: |
echo '&defaults *defaults'
# &defaults and *defaults
Reported (with forbid-duplicated-anchors: true)¶
Reported (with forbid-ambiguous-anchor-alias-names: true)¶
Automatic fixing¶
This rule does not auto-fix; anchor and alias graphs require human judgement to rewrite safely.
Related rules¶
key-duplicates— covers a related class of ambiguity in mappings.