Yamllint: Difference between revisions

(8 intermediate revisions by the same user not shown)

Line 1:

A linter for YAML files. <code>'''yamllint'''</code> does not only check for syntax validity, but for weirdness like key repetition and cosmetic problems such as lines length, trailing spaces, indentation, etc.

Use an online validator like https://www.yamllint.com/ or https://jsonformatter.org/yaml-validator

Of course, you should have one in your local tools and CI pipeline to ensure that your [[YAML]] is always correct.

Of course, you should have one in your local tools and [https://github.com/freephile/meza/blob/e4ba295c4705ba982ae3b5c100ce212d366c1330/.github/workflows/yamllint.yml CI pipeline to ensure] that your [[YAML]] is always correct. With <code>yamllint</code>, there is both a script and a Python module; meaning you can write your own linting tool in Python by invoking (importing) the yamllint module<ref>https://yamllint.readthedocs.io/en/stable/development.html</ref>. See the caveat section below about "using the right tool for the job" - meaning use the right linter for the language/project you are linting.

{{Notice|If you have a <tt>.yamllint</tt> file in your working directory, it will be automatically loaded as configuration by yamllint.}}

==Manually fix errors==

Unfortunately, <tt>yamllint</tt> does not fix your file for you. There could be ambiguities about the proper fix, so you need to do the fix(es) yourself.

== VSCode settings ==

I had a problem with VSCode automatically re-introducing spaces around curly braces - causing the very same yamllint errors I was trying to fix. Despite trying various linters (aka formatters), I ultimately found that the only way to be able to save the correct formatting was to '''disable''' <code>formatOnSave</code> in my user settings. This was because the "default settings" (<code>/defaultSettings.json</code>) was read-only so I could not change it, AND it was configured to <code>formatOnSave</code> - using the kennylong linter which is apparently bad for yaml outside kubernetes contexts.

In VSCode, use <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> to open the preferences dialog and type 'Preferences: Open User Settings' then open User Settings (JSON) settings. Ensure you have lines like this (especially the editor.formatOnSave line because I tried other linters like "redhat.vscode-yaml" without success):<syntaxhighlight lang="json">

"[yaml]": {

"editor.defaultFormatter": "kennylong.kubernetes-yaml-formatter",

"editor.autoIndent": "advanced",

"editor.formatOnSave": false

},

</syntaxhighlight>

==Cheatsheet==

You can use '''[https://yamllint.readthedocs.io/en/stable/disable_with_comments.html comment directives]''' to control the behavior of <code>yamllint</code>

With <code>disable-line</code> you put the directive in-line, or on the line above.<syntaxhighlight lang="yaml">

# The following mapping contains the same key twice,

# but I know what I'm doing:

key: value 1

# yamllint disable-line rule:key-duplicates

key: value 2

# yamllint disable-line rule:line-length

- This line is waaaaaaaaaay too long but yamllint will not report anything about it.

This line will be checked by yamllint.

</syntaxhighlight>With <code>disable</code> you can disable multiple [https://yamllint.readthedocs.io/en/stable/rules.html rules] for the entire file.<syntaxhighlight lang="yaml">

# yamllint disable rule:hyphens rule:commas rule:indentation

</syntaxhighlight>Or even use <code>disable-file</code><syntaxhighlight lang="yaml">

# yamllint disable-file

# This file is not valid YAML because it is a Jinja template

</syntaxhighlight>

<code>--no-warnings</code> will suppress the warnings so you can focus only on errors.

<code>--list-files</code> will show you the list of files that yamllint finds (and would otherwise lint).

<code>--format</code> (or <code>-f</code>) gives you options for how you want the output to display.

== Yaml multiline ==

<blockquote>When writing YAML in your [[Ansible]] playbooks, you run across values that span multiple lines using <code>|</code> or <code>></code>. Spanning multiple lines using a “Literal Block Scalar” <code>|</code> will '''include the newlines''' and any '''trailing''' '''spaces'''. Using a “Folded Block Scalar” <code>></code> will '''fold newlines to spaces.''' It is used to make what would otherwise be a very long line easier to read and edit. In either case the ''indentation (leading spaces) will be ignored''. </blockquote>from [https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html YAML in Ansible] (Community Documentation)

Interactive demonstration of '''Block scalars''' and '''Flow scalars''' https://yaml-multiline.info/

[https://stackoverflow.com/questions/3790454/how-do-i-break-a-string-in-yaml-over-multiple-lines/21699210#21699210 The SO answer that describes them all]

==Many linters==

You can't just use "one" solution either<ref>https://phabricator.wikimedia.org/T95890</ref>. The leading GPL linter is based on Python, so depending on your code repo, you may instead want to use a JavaScript or PHP implementation. Thus, tools like [[wp:Grunt (software)]] may be used to automate JSHint linting in [[JavaScript]] projects<ref>https://www.codereadability.com/jshint-with-grunt/</ref>.

==Source, Docs and Reading==

~~You can't just use "one" solution though~~. ~~The leading GPL linter is based on Python, so depending on your code repo, you may instead want to use a JavaScript or PHP implementation~~. ~~Thus, tools like [[wp~~:~~Grunt (software)]] may be used to automate JSHint linting in [[JavaScript]] projects<ref>~~https://www.~~codereadability~~.com/~~jshint~~-~~with~~-~~grunt~~/</~~ref>~~.

*https://github.com/adrienverge/yamllint

*https://yamllint.readthedocs.io/en/stable/

*https://www.redhat.com/sysadmin/check-yaml-yamllint

* https://www.redhat.com/en/blog/ansible-lists-dictionaries-yaml

* [https://symfony.com/doc/current/reference/formats/yaml.html YAML in Symphony]

* https://~~github~~.~~com~~/~~adrienverge~~/~~yamllint~~

* [https://yaml.org/spec/1.2.2/#scalars YAML 1.2.2 spec on '''scalars''']

* https://~~yamllint.readthedocs~~.io/en/~~stable~~/

* [https://yaml.org/spec/1.2.2/#8112-block-chomping-indicator YAML 1.2.2 spec on '''block chomping''']

@@ Line 1: / Line 1: @@
+A linter for YAML files. <code>'''yamllint'''</code> does not only check for syntax validity, but for weirdness like key repetition and cosmetic problems such as lines length, trailing spaces, indentation, etc.
 Use an online validator like https://www.yamllint.com/ or https://jsonformatter.org/yaml-validator
-Of course, you should have one in your local tools and CI pipeline to ensure that your [[YAML]] is always correct.
+Of course, you should have one in your local tools and [https://github.com/freephile/meza/blob/e4ba295c4705ba982ae3b5c100ce212d366c1330/.github/workflows/yamllint.yml CI pipeline to ensure] that your [[YAML]] is always correct. With <code>yamllint</code>, there is both a script and a Python module; meaning you can write your own linting tool in Python by invoking (importing) the yamllint module<ref>https://yamllint.readthedocs.io/en/stable/development.html</ref>. See the caveat section below about "using the right tool for the job" - meaning use the right linter for the language/project you are linting.
+{{Notice|If you have a <tt>.yamllint</tt> file in your working directory, it will be automatically loaded as configuration by yamllint.}}
+==Manually fix errors==
+Unfortunately, <tt>yamllint</tt> does not fix your file for you. There could be ambiguities about the proper fix, so you need to do the fix(es) yourself.
+== VSCode settings ==
+I had a problem with VSCode automatically re-introducing spaces around curly braces - causing the very same yamllint errors I was trying to fix. Despite trying various linters (aka formatters), I ultimately found that the only way to be able to save the correct formatting was to '''disable''' <code>formatOnSave</code> in my user settings. This was because the "default settings" (<code>/defaultSettings.json</code>) was read-only so I could not change it, AND it was configured to <code>formatOnSave</code> - using the kennylong linter which is apparently bad for yaml outside kubernetes contexts.
+In VSCode, use <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> to open the preferences dialog and type 'Preferences: Open User Settings' then open User Settings (JSON) settings. Ensure you have lines like this (especially the editor.formatOnSave line because I tried other linters like "redhat.vscode-yaml" without success):<syntaxhighlight lang="json">
+	"[yaml]": {
+		"editor.defaultFormatter": "kennylong.kubernetes-yaml-formatter",
+		"editor.autoIndent": "advanced",
+		"editor.formatOnSave": false
+	},
+</syntaxhighlight>
+==Cheatsheet==
+You can use '''[https://yamllint.readthedocs.io/en/stable/disable_with_comments.html comment directives]''' to control the behavior of <code>yamllint</code>
+With <code>disable-line</code> you put the directive in-line, or on the line above.<syntaxhighlight lang="yaml">
+# The following mapping contains the same key twice,
+# but I know what I'm doing:
+key: value 1
+# yamllint disable-line rule:key-duplicates
+key: value 2
+# yamllint disable-line rule:line-length
+- This line is waaaaaaaaaay too long but yamllint will not report anything about it.
+  This line will be checked by yamllint.
+</syntaxhighlight>With <code>disable</code> you can disable multiple [https://yamllint.readthedocs.io/en/stable/rules.html rules] for the entire file.<syntaxhighlight lang="yaml">
+# yamllint disable rule:hyphens rule:commas rule:indentation
+</syntaxhighlight>Or even use <code>disable-file</code><syntaxhighlight lang="yaml">
+# yamllint disable-file
+# This file is not valid YAML because it is a Jinja template
+</syntaxhighlight>
+<code>--no-warnings</code> will suppress the warnings so you can focus only on errors.
+<code>--list-files</code> will show you the list of files that yamllint finds (and would otherwise lint).
+<code>--format</code> (or <code>-f</code>) gives you options for how you want the output to display.
+== Yaml multiline ==
+<blockquote>When writing YAML in your [[Ansible]] playbooks, you run across values that span multiple lines using <code>|</code> or <code>></code>. Spanning multiple lines using a “Literal Block Scalar” <code>|</code> will '''include the newlines''' and any '''trailing''' '''spaces'''. Using a “Folded Block Scalar” <code>></code> will '''fold newlines to spaces.''' It is used to make what would otherwise be a very long line easier to read and edit. In either case the ''indentation (leading spaces) will be ignored''. </blockquote>from [https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html YAML in Ansible] (Community Documentation)
+Interactive demonstration of '''Block scalars''' and '''Flow scalars''' https://yaml-multiline.info/
+[https://stackoverflow.com/questions/3790454/how-do-i-break-a-string-in-yaml-over-multiple-lines/21699210#21699210 The SO answer that describes them all]
+==Many linters==
+You can't just use "one" solution either<ref>https://phabricator.wikimedia.org/T95890</ref>. The leading GPL linter is based on Python, so depending on your code repo, you may instead want to use a JavaScript or PHP implementation. Thus, tools like [[wp:Grunt (software)]] may be used to automate JSHint linting in [[JavaScript]] projects<ref>https://www.codereadability.com/jshint-with-grunt/</ref>.
+==Source, Docs and Reading==
-You can't just use "one" solution though. The leading GPL linter is based on Python, so depending on your code repo, you may instead want to use a JavaScript or PHP implementation. Thus, tools like [[wp:Grunt (software)]] may be used to automate JSHint linting in [[JavaScript]] projects<ref>https://www.codereadability.com/jshint-with-grunt/</ref>.
+*https://github.com/adrienverge/yamllint
+*https://yamllint.readthedocs.io/en/stable/
+*https://www.redhat.com/sysadmin/check-yaml-yamllint
+* https://www.redhat.com/en/blog/ansible-lists-dictionaries-yaml
+* [https://symfony.com/doc/current/reference/formats/yaml.html YAML in Symphony]
-* https://github.com/adrienverge/yamllint
+* [https://yaml.org/spec/1.2.2/#scalars YAML 1.2.2 spec on '''scalars''']
-* https://yamllint.readthedocs.io/en/stable/
+* [https://yaml.org/spec/1.2.2/#8112-block-chomping-indicator YAML 1.2.2 spec on '''block chomping''']
 {{References}}