Configuration¶
yamllint uses a set of rules to check source files for problems. Each rule is independent from the others, and can be enabled, disabled or tweaked. All these settings can be gathered in a configuration file.
To use a custom configuration file, use the -c
option:
yamllint -c /path/to/myconfig file-to-lint.yaml
If -c
is not provided, yamllint will look for a configuration file in the
following locations (by order of preference):
.yamllint
,.yamllint.yaml
or.yamllint.yml
in the current working directory- the file referenced by
$YAMLLINT_CONFIG_FILE
, if set $XDG_CONFIG_HOME/yamllint/config
~/.config/yamllint/config
Finally if no config file is found, the default configuration is applied.
Default configuration¶
Unless told otherwise, yamllint uses its default
configuration:
---
yaml-files:
- '*.yaml'
- '*.yml'
- '.yamllint'
rules:
braces: enable
brackets: enable
colons: enable
commas: enable
comments:
level: warning
comments-indentation:
level: warning
document-end: disable
document-start:
level: warning
empty-lines: enable
empty-values: disable
hyphens: enable
indentation: enable
key-duplicates: enable
key-ordering: disable
line-length: enable
new-line-at-end-of-file: enable
new-lines: enable
octal-values: disable
quoted-strings: disable
trailing-spaces: enable
truthy:
level: warning
Details on rules can be found on the rules page.
There is another pre-defined configuration named relaxed
. As its name
suggests, it is more tolerant:
---
extends: default
rules:
braces:
level: warning
max-spaces-inside: 1
brackets:
level: warning
max-spaces-inside: 1
colons:
level: warning
commas:
level: warning
comments: disable
comments-indentation: disable
document-start: disable
empty-lines:
level: warning
hyphens:
level: warning
indentation:
level: warning
indent-sequences: consistent
line-length:
level: warning
allow-non-breakable-inline-mappings: true
truthy: disable
It can be chosen using:
yamllint -d relaxed file.yml
Extending the default configuration¶
When writing a custom configuration file, you don’t need to redefine every
rule. Just extend the default
configuration (or any already-existing
configuration file).
For instance, if you just want to disable the comments-indentation
rule,
your file could look like this:
# This is my first, very own configuration file for yamllint!
# It extends the default conf by adjusting some options.
extends: default
rules:
comments-indentation: disable # don't bother me with this rule
Similarly, if you want to set the line-length
rule as a warning and be less
strict on block sequences indentation:
extends: default
rules:
# 80 chars should be enough, but don't fail if a line is longer
line-length:
max: 80
level: warning
# accept both key:
# - item
#
# and key:
# - item
indentation:
indent-sequences: whatever
Custom configuration without a config file¶
It is possible – although not recommended – to pass custom configuration
options to yamllint with the -d
(short for --config-data
) option.
Its content can either be the name of a pre-defined conf (example: default
or relaxed
) or a serialized YAML object describing the configuration.
For instance:
yamllint -d "{extends: relaxed, rules: {line-length: {max: 120}}}" file.yaml
Errors and warnings¶
Problems detected by yamllint can be raised either as errors or as warnings.
The CLI will output them (with different colors when using the colored
output format, or auto
when run from a terminal).
By default the script will exit with a return code 1
only when there is
one or more error(s).
However if strict mode is enabled with the -s
(or --strict
) option, the
return code will be:
0
if no errors or warnings occur1
if one or more errors occur2
if no errors occur, but one or more warnings occur
If the script is invoked with the --no-warnings
option, it won’t output
warning level problems, only error level ones.
YAML files extensions¶
To configure what yamllint should consider as YAML files, set yaml-files
configuration option. The default is:
yaml-files:
- '*.yaml'
- '*.yml'
- '.yamllint'
The same rules as for ignoring paths apply (.gitignore
-style path pattern,
see below).
Ignoring paths¶
It is possible to exclude specific files or directories, so that the linter doesn’t process them.
You can either totally ignore files (they won’t be looked at):
extends: default
ignore: |
/this/specific/file.yaml
all/this/directory/
*.template.yaml
or ignore paths only for specific rules:
extends: default
rules:
trailing-spaces:
ignore: |
/this-file-has-trailing-spaces-but-it-is-OK.yaml
/generated/*.yaml
Note that this .gitignore
-style path pattern allows complex path
exclusion/inclusion, see the pathspec README file for more details.
Here is a more complex example:
# For all rules
ignore: |
*.dont-lint-me.yaml
/bin/
!/bin/*.lint-me-anyway.yaml
extends: default
rules:
key-duplicates:
ignore: |
generated
*.template.yaml
trailing-spaces:
ignore: |
*.ignore-trailing-spaces.yaml
ascii-art/*