Rules¶
When linting a document with yamllint, a series of rules (such as
line-length
, trailing-spaces
, etc.) are checked against.
A configuration file can be used to enable or disable these rules, to set their level (error or warning), but also to tweak their options.
This page describes the rules and their options.
List of rules
braces¶
Use this rule to control the number of spaces inside braces ({
and }
).
Options
min-spaces-inside
defines the minimal number of spaces required inside braces.max-spaces-inside
defines the maximal number of spaces allowed inside braces.
Examples
With
braces: {min-spaces-inside: 0, max-spaces-inside: 0}
the following code snippet would PASS:
object: {key1: 4, key2: 8}
the following code snippet would FAIL:
object: { key1: 4, key2: 8 }
With
braces: {min-spaces-inside: 1, max-spaces-inside: 3}
the following code snippet would PASS:
object: { key1: 4, key2: 8 }
the following code snippet would PASS:
object: { key1: 4, key2: 8 }
the following code snippet would FAIL:
object: { key1: 4, key2: 8 }
the following code snippet would FAIL:
object: {key1: 4, key2: 8 }
brackets¶
Use this rule to control the number of spaces inside brackets ([
and
]
).
Options
min-spaces-inside
defines the minimal number of spaces required inside brackets.max-spaces-inside
defines the maximal number of spaces allowed inside brackets.
Examples
With
brackets: {min-spaces-inside: 0, max-spaces-inside: 0}
the following code snippet would PASS:
object: [1, 2, abc]
the following code snippet would FAIL:
object: [ 1, 2, abc ]
With
brackets: {min-spaces-inside: 1, max-spaces-inside: 3}
the following code snippet would PASS:
object: [ 1, 2, abc ]
the following code snippet would PASS:
object: [ 1, 2, abc ]
the following code snippet would FAIL:
object: [ 1, 2, abc ]
the following code snippet would FAIL:
object: [1, 2, abc ]
colons¶
Use this rule to control the number of spaces before and after colons (:
).
Options
max-spaces-before
defines the maximal number of spaces allowed before colons (use-1
to disable).max-spaces-after
defines the maximal number of spaces allowed after colons (use-1
to disable).
Examples
With
colons: {max-spaces-before: 0, max-spaces-after: 1}
the following code snippet would PASS:
object: - a - b key: value
With
colons: {max-spaces-before: 1}
the following code snippet would PASS:
object : - a - b
the following code snippet would FAIL:
object : - a - b
With
colons: {max-spaces-after: 2}
the following code snippet would PASS:
first: 1 second: 2 third: 3
the following code snippet would FAIL:
first: 1 2nd: 2 third: 3
commas¶
Use this rule to control the number of spaces before and after commas (,
).
Options
max-spaces-before
defines the maximal number of spaces allowed before commas (use-1
to disable).min-spaces-after
defines the minimal number of spaces required after commas.max-spaces-after
defines the maximal number of spaces allowed after commas (use-1
to disable).
Examples
With
commas: {max-spaces-before: 0}
the following code snippet would PASS:
strange var: [10, 20, 30, {x: 1, y: 2}]
the following code snippet would FAIL:
strange var: [10, 20 , 30, {x: 1, y: 2}]
With
commas: {max-spaces-before: 2}
the following code snippet would PASS:
strange var: [10 , 20 , 30, {x: 1 , y: 2}]
With
commas: {max-spaces-before: -1}
the following code snippet would PASS:
strange var: [10, 20 , 30 , {x: 1, y: 2}]
With
commas: {min-spaces-after: 1, max-spaces-after: 1}
the following code snippet would PASS:
strange var: [10, 20,30, {x: 1, y: 2}]
the following code snippet would FAIL:
strange var: [10, 20,30, {x: 1, y: 2}]
With
commas: {min-spaces-after: 1, max-spaces-after: 3}
the following code snippet would PASS:
strange var: [10, 20, 30, {x: 1, y: 2}]
With
commas: {min-spaces-after: 0, max-spaces-after: 1}
the following code snippet would PASS:
strange var: [10, 20,30, {x: 1, y: 2}]
comments¶
Use this rule to control the position and formatting of comments.
Options
- Use
require-starting-space
to require a space character right after the#
. Set toyes
to enable,no
to disable. min-spaces-from-content
is used to visually separate inline comments from content. It defines the minimal required number of spaces between a comment and its preceding content.
Examples
With
comments: {require-starting-space: yes}
the following code snippet would PASS:
# This sentence # is a block comment
the following code snippet would FAIL:
#This sentence #is a block comment
With
comments: {min-spaces-from-content: 2}
the following code snippet would PASS:
x = 2 ^ 127 - 1 # Mersenne prime number
the following code snippet would FAIL:
x = 2 ^ 127 - 1 # Mersenne prime number
comments-indentation¶
Use this rule to force comments to be indented like content.
Examples
With
comments-indentation: {}
the following code snippet would PASS:
# Fibonacci [0, 1, 1, 2, 3, 5]
the following code snippet would FAIL:
# Fibonacci [0, 1, 1, 2, 3, 5]
the following code snippet would PASS:
list: - 2 - 3 # - 4 - 5
the following code snippet would FAIL:
list: - 2 - 3 # - 4 - 5
the following code snippet would PASS:
# This is the first object obj1: - item A # - item B # This is the second object obj2: []
the following code snippet would PASS:
# This sentence # is a block comment
the following code snippet would FAIL:
# This sentence # is a block comment
document-end¶
Use this rule to require or forbid the use of document end marker (...
).
Options
- Set
present
toyes
when the document end marker is required, or tono
when it is forbidden.
Examples
With
document-end: {present: yes}
the following code snippet would PASS:
--- this: is: [a, document] ... --- - this - is: another one ...
the following code snippet would FAIL:
--- this: is: [a, document] --- - this - is: another one ...
With
document-end: {present: no}
the following code snippet would PASS:
--- this: is: [a, document] --- - this - is: another one
the following code snippet would FAIL:
--- this: is: [a, document] ... --- - this - is: another one
document-start¶
Use this rule to require or forbid the use of document start marker (---
).
Options
- Set
present
toyes
when the document start marker is required, or tono
when it is forbidden.
Examples
With
document-start: {present: yes}
the following code snippet would PASS:
--- this: is: [a, document] --- - this - is: another one
the following code snippet would FAIL:
this: is: [a, document] --- - this - is: another one
With
document-start: {present: no}
the following code snippet would PASS:
this: is: [a, document] ...
the following code snippet would FAIL:
--- this: is: [a, document] ...
empty-lines¶
Use this rule to set a maximal number of allowed consecutive blank lines.
Options
max
defines the maximal number of empty lines allowed in the document.max-start
defines the maximal number of empty lines allowed at the beginning of the file. This option takes precedence overmax
.max-end
defines the maximal number of empty lines allowed at the end of the file. This option takes precedence overmax
.
Examples
With
empty-lines: {max: 1}
the following code snippet would PASS:
- foo: - 1 - 2 - bar: [3, 4]
the following code snippet would FAIL:
- foo: - 1 - 2 - bar: [3, 4]
hyphens¶
Use this rule to control the number of spaces after hyphens (-
).
Options
max-spaces-after
defines the maximal number of spaces allowed after hyphens.
Examples
With
hyphens: {max-spaces-after: 1}
the following code snippet would PASS:
- first list: - a - b - - 1 - 2 - 3
the following code snippet would FAIL:
- first list: - a - b
the following code snippet would FAIL:
- - 1 - 2 - 3
With
hyphens: {max-spaces-after: 3}
the following code snippet would PASS:
- key - key2 - key42
the following code snippet would FAIL:
- key - key2 - key42
indentation¶
Use this rule to control the indentation.
Options
spaces
defines the indentation width, in spaces. Set either to an integer (e.g.2
or4
, representing the number of spaces in an indentation level) or toconsistent
to allow any number, as long as it remains the same within the file.indent-sequences
defines whether block sequences should be indented or not (when in a mapping, this indentation is not mandatory – some people perceive the-
as part of the indentation). Possible values:yes
,no
,whatever
andconsistent
.consistent
requires either all block sequences to be indented, or none to be.whatever
means either indenting or not indenting individual block sequences is OK.check-multi-line-strings
defines whether to lint indentation in multi-line strings. Set toyes
to enable,no
to disable.
Examples
With
indentation: {spaces: 1}
the following code snippet would PASS:
history: - name: Unix date: 1969 - name: Linux date: 1991 nest: recurse: - haystack: needle
With
indentation: {spaces: 4}
the following code snippet would PASS:
history: - name: Unix date: 1969 - name: Linux date: 1991 nest: recurse: - haystack: needle
the following code snippet would FAIL:
history: - name: Unix date: 1969 - name: Linux date: 1991 nest: recurse: - haystack: needle
With
indentation: {spaces: consistent}
the following code snippet would PASS:
history: - name: Unix date: 1969 - name: Linux date: 1991 nest: recurse: - haystack: needle
the following code snippet would FAIL:
some: Russian: dolls
With
indentation: {spaces: 2, indent-sequences: no}
the following code snippet would PASS:
list: - flying - spaghetti - monster
the following code snippet would FAIL:
list: - flying - spaghetti - monster
With
indentation: {spaces: 2, indent-sequences: whatever}
the following code snippet would PASS:
list: - flying: - spaghetti - monster - not flying: - spaghetti - sauce
With
indentation: {spaces: 2, indent-sequences: consistent}
the following code snippet would PASS:
- flying: - spaghetti - monster - not flying: - spaghetti - sauce
the following code snippet would FAIL:
- flying: - spaghetti - monster - not flying: - spaghetti - sauce
With
indentation: {spaces: 4, check-multi-line-strings: yes}
the following code snippet would PASS:
Blaise Pascal: Je vous écris une longue lettre parce que je n'ai pas le temps d'en écrire une courte.
the following code snippet would PASS:
Blaise Pascal: Je vous écris une longue lettre parce que je n'ai pas le temps d'en écrire une courte.
the following code snippet would FAIL:
Blaise Pascal: Je vous écris une longue lettre parce que je n'ai pas le temps d'en écrire une courte.
the following code snippet would FAIL:
C code: void main() { printf("foo"); }
the following code snippet would PASS:
C code: void main() { printf("bar"); }
key-duplicates¶
Use this rule to prevent multiple entries with the same key in mappings.
Examples
With
key-duplicates: {}
the following code snippet would PASS:
- key 1: v key 2: val key 3: value - {a: 1, b: 2, c: 3}
the following code snippet would FAIL:
- key 1: v key 2: val key 1: value
the following code snippet would FAIL:
- {a: 1, b: 2, b: 3}
the following code snippet would FAIL:
duplicated key: 1 "duplicated key": 2 other duplication: 1 ? >- other duplication : 2
line-length¶
Use this rule to set a limit to lines length.
Options
max
defines the maximal (inclusive) length of lines.allow-non-breakable-words
is used to allow non breakable words (without spaces inside) to overflow the limit. This is useful for long URLs, for instance. Useyes
to allow,no
to forbid.
Examples
With
line-length: {max: 70}
the following code snippet would PASS:
long sentence: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
the following code snippet would FAIL:
long sentence: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
With
line-length: {max: 60, allow-non-breakable-words: yes}
the following code snippet would PASS:
this: is: - a: http://localhost/very/very/very/very/very/very/very/very/long/url # this comment is too long, # but hard to split: # http://localhost/another/very/very/very/very/very/very/very/very/long/url
the following code snippet would FAIL:
- this line is waaaaaaaaaaaaaay too long but could be easily splitted...
With
line-length: {max: 60, allow-non-breakable-words: no}
the following code snippet would FAIL:
this: is: - a: http://localhost/very/very/very/very/very/very/very/very/long/url
new-line-at-end-of-file¶
Use this rule to require a new line character (\n
) at the end of files.
The POSIX standard requires the last line to end with a new line character. All UNIX tools expect a new line at the end of files. Most text editors use this convention too.
new-lines¶
Use this rule to force the type of new line characters.
Options
- Set
type
tounix
to use UNIX-typed new line characters (\n
), ordos
to use DOS-typed new line characters (\r\n
).
trailing-spaces¶
Use this rule to forbid trailing spaces at the end of lines.
Examples
With
trailing-spaces: {}
the following code snippet would PASS:
this document doesn't contain any trailing spaces
the following code snippet would FAIL:
this document contains trailing spaces on lines 1 and 3