What formatting does to a YAML file
The formatter reads the whole file, then writes it again with a consistent layout. The data stays the same. What changes:
- Every level is indented by the same amount, with spaces. Lines that were indented in a mix of widths are made uniform.
- Spacing is tidied: one space after a colon and one before a trailing comment.
- Runs of blank lines become one blank line.
- Inline collections get spaces inside the brackets, as in
{ a: 1 }. The Expand option writes them as indented lines instead. - A plain value that continues over several lines is joined into one line. It means the same.
What stays: comments, anchors (&name) and aliases (*name), block text written with | or >, tags, and the order of keys and list items. A file with several documents separated by --- stays several documents.
Why your values are not rewritten
YAML tools do not agree on what a plain value means. The text 0755 is the octal number 493 to a YAML 1.1 parser and the decimal number 755 to a YAML 1.2 parser. yes and NO are booleans in 1.1 and plain text in 1.2. 22:22 can be a base 60 number in 1.1.
A formatter that reads values as numbers and writes them back would turn 0755 into 755 and 1e3 into 1e+3, silently changing a config file that another tool reads. This one treats every plain value as text and writes the same text back, so a file mode, a version or a port mapping is never altered.
The YAML validator page lists the values in your file that different YAML versions read differently.
Common YAML mistakes
- Tabs for indentation. YAML does not allow them. Use spaces.
- Inconsistent indentation. Keys at the same level must start in the same column, and children must be indented more than their parent.
- A colon and a space inside a value.
title: Note: read thisis an error. Put the value in quotes. - No space after the colon.
key:valueis valid YAML, but it is one text value, not a key with a value. - Duplicate keys. The same key twice in one mapping. Most loaders keep only the last.
- A value that starts with a special character. Values that start with
@, a backtick or%need quotes. - An alias with no anchor.
*namemust refer to a&namedefined earlier.
Sorting, wrapping and quote style
Sort keys reorders every mapping A to Z. The order of mapping keys carries no meaning in the YAML specification, but some tools and people rely on it, so check before you sort a file that others read. List order is never changed. If sorting would put an alias before its anchor, the tool stops and tells you, because that would make the file invalid.
Long lines are never wrapped by default. Choose 80 or 120 to fold long text values at that width. The folded text means the same. Quotes can be kept as written, or normalised to double or single quotes where the value allows it.