Configuration ============= yamllint uses a set of :doc:`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 `. 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 `_ 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 `_, 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