xenial (1) yamllint.1.gz

Provided by: yamllint_1.2.1-1_amd64 bug

NAME

       yamllint -

       A linter for YAML files.

       yamllint  does  not  only check for syntax validity, but for weirdnesses like key repetition and cosmetic
       problems such as lines length, trailing spaces, indentation, etc.

SCREENSHOT

       [image: yamllint screenshot] [image]

       NOTE:
          The default output format is inspired by eslint, a great linting tool for Javascript.

TABLE OF CONTENTS

   Quickstart
   Installing yamllint
       On Fedora / CentOS:

          sudo dnf install yamllint

       On Debian 9+ / Ubuntu 16.04+:

          sudo apt-get install yamllint

       On older Debian / Ubuntu versions:

          sudo add-apt-repository -y ppa:adrienverge/ppa && sudo apt-get update
          sudo apt-get install yamllint

       Alternatively using pip, the Python package manager:

          sudo pip install yamllint

       If you prefer installing from source, you can run, from the source directory:

          python setup.py sdist
          sudo pip install dist/yamllint-*.tar.gz

   Running yamllint
       Basic usage:

          yamllint file.yml other-file.yaml

       You can also lint all YAML files in a whole directory:

          yamllint .

       The output will look like (colors are not displayed here):

          file.yml
            1:4       error    trailing spaces  (trailing-spaces)
            4:4       error    wrong indentation: expected 4 but found 3  (indentation)
            5:4       error    duplication of key "id-00042" in mapping  (key-duplicates)
            6:6       warning  comment not indented like content  (comments-indentation)
            12:6      error    too many spaces after hyphen  (hyphens)
            15:12     error    too many spaces before comma  (commas)

          other-file.yaml
            1:1       warning  missing document start "---"  (document-start)
            6:81      error    line too long (87 > 80 characters)  (line-length)
            10:1      error    too many blank lines (4 > 2)  (empty-lines)
            11:4      error    too many spaces inside braces  (braces)

       Add the -f parsable arguments if you need an output format parsable by a machine (for instance for syntax
       highlighting in text editors). The output will then look like:

          file.yml:6:2: [warning] missing starting space in comment (comments)
          file.yml:57:1: [error] trailing spaces (trailing-spaces)
          file.yml:60:3: [error] wrong indentation: expected 4 but found 2 (indentation)

       If  you  have  a  custom  linting configuration file (see how to configure yamllint), it can be passed to
       yamllint using the -c option:

          yamllint -c ~/myconfig file.yaml

       NOTE:
          If you have a  .yamllint  file  in  your  working  directory,  it  will  be  automatically  loaded  as
          configuration by yamllint.

   Configuration
       yamllint  uses  a  set  of  rules  to check sources 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, either name it .yamllint in your working directory, or use the -c
       option:

          yamllint -c ~/myconfig file.yaml

   Default configuration
       Unless told otherwise, yamllint uses its default configuration:

          ---

          rules:
            braces:
              min-spaces-inside: 0
              max-spaces-inside: 0
            brackets:
              min-spaces-inside: 0
              max-spaces-inside: 0
            colons:
              max-spaces-before: 0
              max-spaces-after: 1
            commas:
              max-spaces-before: 0
              min-spaces-after: 1
              max-spaces-after: 1
            comments:
              level: warning
              require-starting-space: yes
              min-spaces-from-content: 2
            comments-indentation:
              level: warning
            document-end: disable
            document-start:
              level: warning
              present: yes
            empty-lines:
              max: 2
              max-start: 0
              max-end: 0
            hyphens:
              max-spaces-after: 1
            indentation:
              spaces: consistent
              indent-sequences: yes
              check-multi-line-strings: no
            key-duplicates: enable
            line-length:
              max: 80
              allow-non-breakable-words: yes
            new-line-at-end-of-file: enable
            new-lines:
              type: unix
            trailing-spaces: enable

       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.

       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.

       In both cases, the script will output them (with different colors when using the standard output format),
       but  the  exit  code can be different. More precisely, the script will exit will a failure code only when
       there is one or more error(s).

   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 rulesbracesbracketscolonscommascommentscomments-indentationdocument-enddocument-startempty-lineshyphensindentationkey-duplicatesline-lengthnew-line-at-end-of-filenew-linestrailing-spaces

   braces
       Use this rule to control the number of spaces inside braces ({ and }).  Options.INDENT 0.0

       • min-spaces-inside defines the minimal number of spaces required inside braces.

       • max-spaces-inside defines the maximal number of spaces allowed inside braces.
       1. 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 }

       2. 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.INDENT 0.0

       • min-spaces-inside defines the minimal number of spaces required inside brackets.

       • max-spaces-inside defines the maximal number of spaces allowed inside brackets.
       1. 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 ]

       2. 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.INDENT 0.0

       • 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).
       1. With colons: {max-spaces-before: 0, max-spaces-after: 1}

          the following code snippet would PASS:

             object:
               - a
               - b
             key: value

       2. With colons: {max-spaces-before: 1}

          the following code snippet would PASS:

             object :
               - a
               - b

          the following code snippet would FAIL:

             object  :
               - a
               - b

       3. 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.INDENT 0.0

       • 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).
       1. 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}]

       2. With commas: {max-spaces-before: 2}

          the following code snippet would PASS:

             strange var:
               [10  , 20 , 30,  {x: 1  , y: 2}]

       3. With commas: {max-spaces-before: -1}

          the following code snippet would PASS:

             strange var:
               [10,
                20   , 30
                ,   {x: 1, y: 2}]

       4. 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}]

       5. 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}]

       6. 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.INDENT 0.0

       • Use require-starting-space to require a space character right after the #. Set to yes 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.
       1. 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

       2. 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.INDENT 0.0

       1. 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.INDENT 0.0

       • Set present to yes when the document end marker is required, or to no when it is forbidden.
       1. 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
             ...

       2. 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.INDENT 0.0

       • Set present to yes when the document start marker is required, or to no when it is forbidden.
       1. 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

       2. 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.INDENT 0.0

       • 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 over max.

       • max-end  defines  the  maximal number of empty lines allowed at the end of the file.  This option takes
         precedence over max.
       1. 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.INDENT 0.0

       • max-spaces-after defines the maximal number of spaces allowed after hyphens.
       1. 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

       2. 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.INDENT 0.0

       • spaces defines the indentation width, in spaces. Set either to an integer (e.g. 2  or  4,  representing
         the  number  of  spaces  in  an  indentation level) or to consistent 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 and  consistent.  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  to  yes  to
         enable, no to disable.
       1. With indentation: {spaces: 1}

          the following code snippet would PASS:

             history:
              - name: Unix
                date: 1969
              - name: Linux
                date: 1991
             nest:
              recurse:
               - haystack:
                  needle

       2. 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

       3. 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

       4. 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

       5. With indentation: {spaces: 2, indent-sequences: whatever}

          the following code snippet would PASS:

             list:
             - flying:
               - spaghetti
               - monster
             - not flying:
                 - spaghetti
                 - sauce

       6. 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

       7. 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.INDENT 0.0

       1. 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.INDENT 0.0

       • 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. Use yes to allow, no to forbid.
       1. 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.

       2. 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...

       3. 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.INDENT 0.0

       • Set  type  to  unix  to  use  UNIX-typed  new  line  characters  (\n), or dos to use DOS-typed new line
         characters (\r\n).

   trailing-spaces
       Use this rule to forbid trailing spaces at the end of lines.  Examples.INDENT 0.0

       1. 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

   Development
       yamllint provides both a script and a Python module. The latter can be used to  write  your  own  linting
       tools:

       class yamllint.linter.LintProblem(line, column, desc='<no description>', rule=None)
              Represents a linting problem found by yamllint.

              column = None
                     Column on which the problem was found (starting at 1)

              desc = None
                     Human-readable description of the problem

              line = None
                     Line on which the problem was found (starting at 1)

              rule = None
                     Identifier of the rule that detected the problem

       yamllint.linter.run(input, conf)
              Lints a YAML source.

              Returns a generator of LintProblem objects.

              Parametersinput -- buffer, string or stream to read from

                     • conf -- yamllint configuration object

   Integration with text editors
       Most text editors support syntax checking and highlighting, to visually report syntax errors and warnings
       to the user. yamllint can be used to syntax-check YAML source, but a bit  of  configuration  is  required
       depending on your favorite text editor.

   Vim
       Assuming that the syntastic plugin is installed, add to your .vimrc:

          let g:syntastic_yaml_checkers = ['yamllint']

   Neovim
       Assuming  that  the  neomake  plugin  is installed, yamllint is supported by default. It is automatically
       enabled when editing YAML files.

   Other text editors
       Help wanted!

       Your favorite text editor is not listed here?  Help  us  improve  by  adding  a  section  (by  opening  a
       pull-request or issue on GitHub).

AUTHOR

       Adrien Vergé

       Copyright 2016, Adrien Vergé