diff options
Diffstat (limited to 'docs/configuration.rst')
| -rw-r--r-- | docs/configuration.rst | 255 |
1 files changed, 255 insertions, 0 deletions
diff --git a/docs/configuration.rst b/docs/configuration.rst new file mode 100644 index 0000000..9624b49 --- /dev/null +++ b/docs/configuration.rst @@ -0,0 +1,255 @@ +Configuration +============= + +yamllint uses a set of :doc:`rules <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: + +.. code:: bash + + 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): + +- a file named ``.yamllint``, ``.yamllint.yaml``, or ``.yamllint.yml`` in the + current working directory, or a parent directory (the search for this file is + terminated at the user's home or filesystem root) +- a filename referenced by ``$YAMLLINT_CONFIG_FILE``, if set +- a file named ``$XDG_CONFIG_HOME/yamllint/config`` or + ``~/.config/yamllint/config``, if present + +Finally if no config file is found, the default configuration is applied. + +Default configuration +--------------------- + +Unless told otherwise, yamllint uses its ``default`` configuration: + +.. literalinclude:: ../yamllint/conf/default.yaml + :language: yaml + +Details on rules can be found on :doc:`the rules page <rules>`. + +There is another pre-defined configuration named ``relaxed``. As its name +suggests, it is more tolerant: + +.. literalinclude:: ../yamllint/conf/relaxed.yaml + :language: yaml + +It can be chosen using: + +.. code:: bash + + 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: + +.. code-block:: yaml + + # 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: + +.. code-block:: yaml + + 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: + +.. code:: bash + + 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 occur + * ``1`` if one or more errors occur + * ``2`` 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 when listing +directories, set ``yaml-files`` configuration option. The default is: + +.. code-block:: yaml + + yaml-files: + - '*.yaml' + - '*.yml' + - '.yamllint' + +The same rules as for ignoring paths apply (``.gitignore``-style path pattern, +see below). + +If you need to know the exact list of files that yamllint would process, +without really linting them, you can use ``--list-files``: + +.. code:: bash + + yamllint --list-files . + +Ignoring paths +-------------- + +It is possible to exclude specific files or directories, so that the linter +doesn't process them. They can be provided either as a list of paths, or as a +bulk string. + +You can either totally ignore files (they won't be looked at): + +.. code-block:: yaml + + extends: default + + ignore: | + /this/specific/file.yaml + all/this/directory/ + *.template.yaml + + # or: + + ignore: + - /this/specific/file.yaml + - all/this/directory/ + - '*.template.yaml' + +or ignore paths only for specific rules: + +.. code-block:: yaml + + extends: default + + rules: + trailing-spaces: + ignore: | + /this-file-has-trailing-spaces-but-it-is-OK.yaml + /generated/*.yaml + + # or: + + 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 +<https://pypi.org/project/pathspec/>`_ for more details. Here is a more complex +example: + +.. code-block:: yaml + + # 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/* + +You can also use the ``.gitignore`` file (or any list of files) through: + +.. code-block:: yaml + + ignore-from-file: .gitignore + +or: + +.. code-block:: yaml + + ignore-from-file: [.gitignore, .yamlignore] + +.. note:: However, this is mutually exclusive with the ``ignore`` key. + +If you need to know the exact list of files that yamllint would process, +without really linting them, you can use ``--list-files``: + +.. code:: bash + + yamllint --list-files . + +Setting the locale +------------------ + +It is possible to set the ``locale`` option globally. This is passed to Python's +`locale.setlocale +<https://docs.python.org/3/library/locale.html#locale.setlocale>`_, +so an empty string ``""`` will use the system default locale, while e.g. +``"en_US.UTF-8"`` will use that. + +Currently this only affects the ``key-ordering`` rule. The default will order +by Unicode code point number, while locales will sort case and accents +properly as well. + +.. code-block:: yaml + + extends: default + + locale: en_US.UTF-8 |