indentation¶
What this rule does¶
Enforces consistent indentation throughout the document. Specifically:
- The indent width used by block mappings and block sequences.
- Whether block sequence items are indented under their parent key or start at the same column.
- Optionally, the indentation of content inside multi-line block scalars.
Why this matters¶
- Mixed indents cause parse surprises. YAML's whitespace sensitivity means inconsistent indents can change which key a value belongs to.
- Cross-tool diffing. Editors with different default tab widths can silently introduce mixed indentation; the rule catches drift early.
- Convention. Most projects settle on either 2- or 4-space indents; pinning the width prevents new files from drifting.
Configuration¶
[lint.rules.indentation]
level = "error"
spaces = "consistent"
indent-sequences = true
check-multi-line-strings = false
| Option | Default | Description |
|---|---|---|
spaces |
top-level indent-width if set, else "consistent" |
An integer such as 2 for a fixed indent width, or "consistent" to lock the rest of the file to the first indent seen. |
indent-sequences |
true |
true, false, "whatever", or "consistent". Whether block sequence items are indented under the parent key. |
check-multi-line-strings |
false |
When true, apply indent checks inside block scalars and multi-line flow strings. |
Examples¶
Allowed (with spaces: 2, indent-sequences: true)¶
Reported (with spaces: 2, indent-sequences: true)¶
Allowed (with indent-sequences: false)¶
Reported (with spaces: 2)¶
Automatic fixing¶
ryl check --fix does not fix this rule; indentation changes can shift values into
different parents.
ryl format re-indents each block level to the top-level indent-width, or without it
to width 2 (see Configuration),
with block sequences indented past their key unless [format] indent-sequences = false.
Block scalar bodies, continuation lines and comments move with the line they belong to,
and lines inside a flow collection go where this rule expects them. A document is left
as it is, and reported, when a tab indents it or when re-indenting it would change what
it parses to; an inline disable for this rule leaves it unreported.
Related rules¶
hyphens— spacing between-and the sequence item value.comments-indentation— standalone comments must follow the same indent as the next line.