1YAMLLINT(1) yamllint YAMLLINT(1)
2
6 yamllint -
7 A linter for YAML files.
9 yamllint does not only check for syntax validity, but for weirdnesses
11 like key repetition and cosmetic problems such as lines length, trail‐
12 ing spaces, indentation, etc.
13
15 [image: yamllint screenshot] [image]
16 NOTE:
18 The default output format is inspired by eslint, a great linting
19 tool for Javascript.
20
22 Quickstart
23 Installing yamllint
24 On Fedora / CentOS (note: EPEL is required on CentOS):
25 sudo dnf install yamllint
27 On Debian 8+ / Ubuntu 16.04+:
29 sudo apt-get install yamllint
31 On Mac OS 10.11+:
33 brew install yamllint
35 On FreeBSD:
37 pkg install py36-yamllint
39 On OpenBSD:
41 doas pkg_add py3-yamllint
43 Alternatively using pip, the Python package manager:
45 pip install --user yamllint
47 If you prefer installing from source, you can run, from the source
49 directory:
50 python setup.py sdist
52 pip install --user dist/yamllint-*.tar.gz
53 Running yamllint
55 Basic usage:
56 yamllint file.yml other-file.yaml
58 You can also lint all YAML files in a whole directory:
60 yamllint .
62 Or lint a YAML stream from standard input:
64 echo -e 'this: is\nvalid: YAML' | yamllint -
66 The output will look like (colors are not displayed here):
68 file.yml
70 1:4 error trailing spaces (trailing-spaces)
71 4:4 error wrong indentation: expected 4 but found 3 (indentation)
72 5:4 error duplication of key "id-00042" in mapping (key-duplicates)
73 6:6 warning comment not indented like content (comments-indentation)
74 12:6 error too many spaces after hyphen (hyphens)
75 15:12 error too many spaces before comma (commas)
76 other-file.yaml
78 1:1 warning missing document start "---" (document-start)
79 6:81 error line too long (87 > 80 characters) (line-length)
80 10:1 error too many blank lines (4 > 2) (empty-lines)
81 11:4 error too many spaces inside braces (braces)
82 By default, the output of yamllint is colored when run from a terminal,
84 and pure text in other cases. Add the -f standard arguments to force
85 non-colored output. Use the -f colored arguments to force colored out‐
86 put.
87 Add the -f parsable arguments if you need an output format parsable by
89 a machine (for instance for syntax highlighting in text editors). The
90 output will then look like:
91 file.yml:6:2: [warning] missing starting space in comment (comments)
93 file.yml:57:1: [error] trailing spaces (trailing-spaces)
94 file.yml:60:3: [error] wrong indentation: expected 4 but found 2 (indentation)
95 If you have a custom linting configuration file (see how to configure
97 yamllint), it can be passed to yamllint using the -c option:
98 yamllint -c ~/myconfig file.yaml
100 NOTE:
102 If you have a .yamllint file in your working directory, it will be
103 automatically loaded as configuration by yamllint.
104 Configuration
106 yamllint uses a set of rules to check source files for problems. Each
107 rule is independent from the others, and can be enabled, disabled or
108 tweaked. All these settings can be gathered in a configuration file.
109 To use a custom configuration file, use the -c option:
111 yamllint -c /path/to/myconfig file-to-lint.yaml
113 If -c is not provided, yamllint will look for a configuration file in
115 the following locations (by order of preference):
116 · .yamllint, .yamllint.yaml or .yamllint.yml in the current working
118 directory
119 · $XDG_CONFIG_HOME/yamllint/config
121 · ~/.config/yamllint/config
123 Finally if no config file is found, the default configuration is
125 applied.
126 Default configuration
128 Unless told otherwise, yamllint uses its default configuration:
129 ---
131 yaml-files:
133 - '*.yaml'
134 - '*.yml'
135 - '.yamllint'
136 rules:
138 braces: enable
139 brackets: enable
140 colons: enable
141 commas: enable
142 comments:
143 level: warning
144 comments-indentation:
145 level: warning
146 document-end: disable
147 document-start:
148 level: warning
149 empty-lines: enable
150 empty-values: disable
151 hyphens: enable
152 indentation: enable
153 key-duplicates: enable
154 key-ordering: disable
155 line-length: enable
156 new-line-at-end-of-file: enable
157 new-lines: enable
158 octal-values: disable
159 quoted-strings: disable
160 trailing-spaces: enable
161 truthy:
162 level: warning
163 Details on rules can be found on the rules page.
166 There is another pre-defined configuration named relaxed. As its name
168 suggests, it is more tolerant:
169 ---
171 extends: default
173 rules:
175 braces:
176 level: warning
177 max-spaces-inside: 1
178 brackets:
179 level: warning
180 max-spaces-inside: 1
181 colons:
182 level: warning
183 commas:
184 level: warning
185 comments: disable
186 comments-indentation: disable
187 document-start: disable
188 empty-lines:
189 level: warning
190 hyphens:
191 level: warning
192 indentation:
193 level: warning
194 indent-sequences: consistent
195 line-length:
196 level: warning
197 allow-non-breakable-inline-mappings: true
198 truthy: disable
199 It can be chosen using:
202 yamllint -d relaxed file.yml
204 Extending the default configuration
206 When writing a custom configuration file, you don't need to redefine
207 every rule. Just extend the default configuration (or any
208 already-existing configuration file).
209 For instance, if you just want to disable the comments-indentation
211 rule, your file could look like this:
212 # This is my first, very own configuration file for yamllint!
214 # It extends the default conf by adjusting some options.
215 extends: default
217 rules:
219 comments-indentation: disable # don't bother me with this rule
220 Similarly, if you want to set the line-length rule as a warning and be
222 less strict on block sequences indentation:
223 extends: default
225 rules:
227 # 80 chars should be enough, but don't fail if a line is longer
228 line-length:
229 max: 80
230 level: warning
231 # accept both key:
233 # - item
234 #
235 # and key:
236 # - item
237 indentation:
238 indent-sequences: whatever
239 Custom configuration without a config file
241 It is possible -- although not recommended -- to pass custom configura‐
242 tion options to yamllint with the -d (short for --config-data) option.
243 Its content can either be the name of a pre-defined conf (example:
245 default or relaxed) or a serialized YAML object describing the configu‐
246 ration.
247 For instance:
249 yamllint -d "{extends: relaxed, rules: {line-length: {max: 120}}}" file.yaml
251 Errors and warnings
253 Problems detected by yamllint can be raised either as errors or as
254 warnings. The CLI will output them (with different colors when using
255 the colored output format, or auto when run from a terminal).
256 By default the script will exit with a return code 1 only when there is
258 one or more error(s).
259 However if strict mode is enabled with the -s (or --strict) option, the
261 return code will be:
262 · 0 if no errors or warnings occur
264 · 1 if one or more errors occur
266 · 2 if no errors occur, but one or more warnings occur
268 YAML files extensions
270 To configure what yamllint should consider as YAML files, set
271 yaml-files configuration option. The default is:
272 yaml-files:
274 - '*.yaml'
275 - '*.yml'
276 - '.yamllint'
277 The same rules as for ignoring paths apply (.gitignore-style path pat‐
279 tern, see below).
280 Ignoring paths
282 It is possible to exclude specific files or directories, so that the
283 linter doesn't process them.
284 You can either totally ignore files (they won't be looked at):
286 extends: default
288 ignore: |
290 /this/specific/file.yaml
291 all/this/directory/
292 *.template.yaml
293 or ignore paths only for specific rules:
295 extends: default
297 rules:
299 trailing-spaces:
300 ignore: |
301 /this-file-has-trailing-spaces-but-it-is-OK.yaml
302 /generated/*.yaml
303 Note that this .gitignore-style path pattern allows complex path exclu‐
305 sion/inclusion, see the pathspec README file for more details. Here is
306 a more complex example:
307 # For all rules
309 ignore: |
310 *.dont-lint-me.yaml
311 /bin/
312 !/bin/*.lint-me-anyway.yaml
313 extends: default
315 rules:
317 key-duplicates:
318 ignore: |
319 generated
320 *.template.yaml
321 trailing-spaces:
322 ignore: |
323 *.ignore-trailing-spaces.yaml
324 ascii-art/*
325 Rules
327 When linting a document with yamllint, a series of rules (such as
328 line-length, trailing-spaces, etc.) are checked against.
329 A configuration file can be used to enable or disable these rules, to
331 set their level (error or warning), but also to tweak their options.
332 This page describes the rules and their options.
334 List of rules
336 · braces
337 · brackets
339 · colons
341 · commas
343 · comments
345 · comments-indentation
347 · document-end
349 · document-start
351 · empty-lines
353 · empty-values
355 · hyphens
357 · indentation
359 · key-duplicates
361 · key-ordering
363 · line-length
365 · new-line-at-end-of-file
367 · new-lines
369 · octal-values
371 · quoted-strings
373 · trailing-spaces
375 · truthy
377 braces
379 Use this rule to control the number of spaces inside braces ({ and }).
380 Options
382 · min-spaces-inside defines the minimal number of spaces required
384 inside braces.
385 · max-spaces-inside defines the maximal number of spaces allowed inside
387 braces.
388 · min-spaces-inside-empty defines the minimal number of spaces required
390 inside empty braces.
391 · max-spaces-inside-empty defines the maximal number of spaces allowed
393 inside empty braces.
394 Examples
396 1. With braces: {min-spaces-inside: 0, max-spaces-inside: 0}
398 the following code snippet would PASS:
400 object: {key1: 4, key2: 8}
402 the following code snippet would FAIL:
404 object: { key1: 4, key2: 8 }
406 2. With braces: {min-spaces-inside: 1, max-spaces-inside: 3}
408 the following code snippet would PASS:
410 object: { key1: 4, key2: 8 }
412 the following code snippet would PASS:
414 object: { key1: 4, key2: 8 }
416 the following code snippet would FAIL:
418 object: { key1: 4, key2: 8 }
420 the following code snippet would FAIL:
422 object: {key1: 4, key2: 8 }
424 3. With braces: {min-spaces-inside-empty: 0, max-spaces-inside-empty:
426 0}
427 the following code snippet would PASS:
429 object: {}
431 the following code snippet would FAIL:
433 object: { }
435 4. With braces: {min-spaces-inside-empty: 1, max-spaces-inside-empty:
437 -1}
438 the following code snippet would PASS:
440 object: { }
442 the following code snippet would FAIL:
444 object: {}
446 brackets
448 Use this rule to control the number of spaces inside brackets ([ and
449 ]).
450 Options
452 · min-spaces-inside defines the minimal number of spaces required
454 inside brackets.
455 · max-spaces-inside defines the maximal number of spaces allowed inside
457 brackets.
458 · min-spaces-inside-empty defines the minimal number of spaces required
460 inside empty brackets.
461 · max-spaces-inside-empty defines the maximal number of spaces allowed
463 inside empty brackets.
464 Examples
466 1. With brackets: {min-spaces-inside: 0, max-spaces-inside: 0}
468 the following code snippet would PASS:
470 object: [1, 2, abc]
472 the following code snippet would FAIL:
474 object: [ 1, 2, abc ]
476 2. With brackets: {min-spaces-inside: 1, max-spaces-inside: 3}
478 the following code snippet would PASS:
480 object: [ 1, 2, abc ]
482 the following code snippet would PASS:
484 object: [ 1, 2, abc ]
486 the following code snippet would FAIL:
488 object: [ 1, 2, abc ]
490 the following code snippet would FAIL:
492 object: [1, 2, abc ]
494 3. With brackets: {min-spaces-inside-empty: 0, max-spaces-inside-empty:
496 0}
497 the following code snippet would PASS:
499 object: []
501 the following code snippet would FAIL:
503 object: [ ]
505 4. With brackets: {min-spaces-inside-empty: 1, max-spaces-inside-empty:
507 -1}
508 the following code snippet would PASS:
510 object: [ ]
512 the following code snippet would FAIL:
514 object: []
516 colons
518 Use this rule to control the number of spaces before and after colons
519 (:).
520 Options
522 · max-spaces-before defines the maximal number of spaces allowed before
524 colons (use -1 to disable).
525 · max-spaces-after defines the maximal number of spaces allowed after
527 colons (use -1 to disable).
528 Examples
530 1. With colons: {max-spaces-before: 0, max-spaces-after: 1}
532 the following code snippet would PASS:
534 object:
536 - a
537 - b
538 key: value
539 2. With colons: {max-spaces-before: 1}
541 the following code snippet would PASS:
543 object :
545 - a
546 - b
547 the following code snippet would FAIL:
549 object :
551 - a
552 - b
553 3. With colons: {max-spaces-after: 2}
555 the following code snippet would PASS:
557 first: 1
559 second: 2
560 third: 3
561 the following code snippet would FAIL:
563 first: 1
565 2nd: 2
566 third: 3
567 commas
569 Use this rule to control the number of spaces before and after commas
570 (,).
571 Options
573 · max-spaces-before defines the maximal number of spaces allowed before
575 commas (use -1 to disable).
576 · min-spaces-after defines the minimal number of spaces required after
578 commas.
579 · max-spaces-after defines the maximal number of spaces allowed after
581 commas (use -1 to disable).
582 Examples
584 1. With commas: {max-spaces-before: 0}
586 the following code snippet would PASS:
588 strange var:
590 [10, 20, 30, {x: 1, y: 2}]
591 the following code snippet would FAIL:
593 strange var:
595 [10, 20 , 30, {x: 1, y: 2}]
596 2. With commas: {max-spaces-before: 2}
598 the following code snippet would PASS:
600 strange var:
602 [10 , 20 , 30, {x: 1 , y: 2}]
603 3. With commas: {max-spaces-before: -1}
605 the following code snippet would PASS:
607 strange var:
609 [10,
610 20 , 30
611 , {x: 1, y: 2}]
612 4. With commas: {min-spaces-after: 1, max-spaces-after: 1}
614 the following code snippet would PASS:
616 strange var:
618 [10, 20,30, {x: 1, y: 2}]
619 the following code snippet would FAIL:
621 strange var:
623 [10, 20,30, {x: 1, y: 2}]
624 5. With commas: {min-spaces-after: 1, max-spaces-after: 3}
626 the following code snippet would PASS:
628 strange var:
630 [10, 20, 30, {x: 1, y: 2}]
631 6. With commas: {min-spaces-after: 0, max-spaces-after: 1}
633 the following code snippet would PASS:
635 strange var:
637 [10, 20,30, {x: 1, y: 2}]
638 comments
640 Use this rule to control the position and formatting of comments.
641 Options
643 · Use require-starting-space to require a space character right after
645 the #. Set to true to enable, false to disable.
646 · Use ignore-shebangs to ignore a shebang at the beginning of the file
648 when require-starting-space is set.
649 · min-spaces-from-content is used to visually separate inline comments
651 from content. It defines the minimal required number of spaces
652 between a comment and its preceding content.
653 Examples
655 1. With comments: {require-starting-space: true}
657 the following code snippet would PASS:
659 # This sentence
661 # is a block comment
662 the following code snippet would PASS:
664 ##############################
666 ## This is some documentation
667 the following code snippet would FAIL:
669 #This sentence
671 #is a block comment
672 2. With comments: {min-spaces-from-content: 2}
674 the following code snippet would PASS:
676 x = 2 ^ 127 - 1 # Mersenne prime number
678 the following code snippet would FAIL:
680 x = 2 ^ 127 - 1 # Mersenne prime number
682 comments-indentation
684 Use this rule to force comments to be indented like content.
685 Examples
687 1. With comments-indentation: {}
689 the following code snippet would PASS:
691 # Fibonacci
693 [0, 1, 1, 2, 3, 5]
694 the following code snippet would FAIL:
696 # Fibonacci
698 [0, 1, 1, 2, 3, 5]
699 the following code snippet would PASS:
701 list:
703 - 2
704 - 3
705 # - 4
706 - 5
707 the following code snippet would FAIL:
709 list:
711 - 2
712 - 3
713 # - 4
714 - 5
715 the following code snippet would PASS:
717 # This is the first object
719 obj1:
720 - item A
721 # - item B
722 # This is the second object
723 obj2: []
724 the following code snippet would PASS:
726 # This sentence
728 # is a block comment
729 the following code snippet would FAIL:
731 # This sentence
733 # is a block comment
734 document-end
736 Use this rule to require or forbid the use of document end marker
737 (...).
738 Options
740 · Set present to true when the document end marker is required, or to
742 false when it is forbidden.
743 Examples
745 1. With document-end: {present: true}
747 the following code snippet would PASS:
749 ---
751 this:
752 is: [a, document]
753 ...
754 ---
755 - this
756 - is: another one
757 ...
758 the following code snippet would FAIL:
760 ---
762 this:
763 is: [a, document]
764 ---
765 - this
766 - is: another one
767 ...
768 2. With document-end: {present: false}
770 the following code snippet would PASS:
772 ---
774 this:
775 is: [a, document]
776 ---
777 - this
778 - is: another one
779 the following code snippet would FAIL:
781 ---
783 this:
784 is: [a, document]
785 ...
786 ---
787 - this
788 - is: another one
789 document-start
791 Use this rule to require or forbid the use of document start marker
792 (---).
793 Options
795 · Set present to true when the document start marker is required, or to
797 false when it is forbidden.
798 Examples
800 1. With document-start: {present: true}
802 the following code snippet would PASS:
804 ---
806 this:
807 is: [a, document]
808 ---
809 - this
810 - is: another one
811 the following code snippet would FAIL:
813 this:
815 is: [a, document]
816 ---
817 - this
818 - is: another one
819 2. With document-start: {present: false}
821 the following code snippet would PASS:
823 this:
825 is: [a, document]
826 ...
827 the following code snippet would FAIL:
829 ---
831 this:
832 is: [a, document]
833 ...
834 empty-lines
836 Use this rule to set a maximal number of allowed consecutive blank
837 lines.
838 Options
840 · max defines the maximal number of empty lines allowed in the docu‐
842 ment.
843 · max-start defines the maximal number of empty lines allowed at the
845 beginning of the file. This option takes precedence over max.
846 · max-end defines the maximal number of empty lines allowed at the end
848 of the file. This option takes precedence over max.
849 Examples
851 1. With empty-lines: {max: 1}
853 the following code snippet would PASS:
855 - foo:
857 - 1
858 - 2
859 - bar: [3, 4]
861 the following code snippet would FAIL:
863 - foo:
865 - 1
866 - 2
867 - bar: [3, 4]
870 empty-values
872 Use this rule to prevent nodes with empty content, that implicitly
873 result in null values.
874 Options
876 · Use forbid-in-block-mappings to prevent empty values in block map‐
878 pings.
879 · Use forbid-in-flow-mappings to prevent empty values in flow mappings.
881 Examples
883 1. With empty-values: {forbid-in-block-mappings: true}
885 the following code snippets would PASS:
887 some-mapping:
889 sub-element: correctly indented
890 explicitly-null: null
892 the following code snippets would FAIL:
894 some-mapping:
896 sub-element: incorrectly indented
897 implicitly-null:
899 2. With empty-values: {forbid-in-flow-mappings: true}
901 the following code snippet would PASS:
903 {prop: null}
905 {a: 1, b: 2, c: 3}
906 the following code snippets would FAIL:
908 {prop: }
910 {a: 1, b:, c: 3}
912 hyphens
914 Use this rule to control the number of spaces after hyphens (-).
915 Options
917 · max-spaces-after defines the maximal number of spaces allowed after
919 hyphens.
920 Examples
922 1. With hyphens: {max-spaces-after: 1}
924 the following code snippet would PASS:
926 - first list:
928 - a
929 - b
930 - - 1
931 - 2
932 - 3
933 the following code snippet would FAIL:
935 - first list:
937 - a
938 - b
939 the following code snippet would FAIL:
941 - - 1
943 - 2
944 - 3
945 2. With hyphens: {max-spaces-after: 3}
947 the following code snippet would PASS:
949 - key
951 - key2
952 - key42
953 the following code snippet would FAIL:
955 - key
957 - key2
958 - key42
959 indentation
961 Use this rule to control the indentation.
962 Options
964 · spaces defines the indentation width, in spaces. Set either to an
966 integer (e.g. 2 or 4, representing the number of spaces in an inden‐
967 tation level) or to consistent to allow any number, as long as it
968 remains the same within the file.
969 · indent-sequences defines whether block sequences should be indented
971 or not (when in a mapping, this indentation is not mandatory -- some
972 people perceive the - as part of the indentation). Possible values:
973 true, false, whatever and consistent. consistent requires either all
974 block sequences to be indented, or none to be. whatever means either
975 indenting or not indenting individual block sequences is OK.
976 · check-multi-line-strings defines whether to lint indentation in
978 multi-line strings. Set to true to enable, false to disable.
979 Examples
981 1. With indentation: {spaces: 1}
983 the following code snippet would PASS:
985 history:
987 - name: Unix
988 date: 1969
989 - name: Linux
990 date: 1991
991 nest:
992 recurse:
993 - haystack:
994 needle
995 2. With indentation: {spaces: 4}
997 the following code snippet would PASS:
999 history:
1001 - name: Unix
1002 date: 1969
1003 - name: Linux
1004 date: 1991
1005 nest:
1006 recurse:
1007 - haystack:
1008 needle
1009 the following code snippet would FAIL:
1011 history:
1013 - name: Unix
1014 date: 1969
1015 - name: Linux
1016 date: 1991
1017 nest:
1018 recurse:
1019 - haystack:
1020 needle
1021 3. With indentation: {spaces: consistent}
1023 the following code snippet would PASS:
1025 history:
1027 - name: Unix
1028 date: 1969
1029 - name: Linux
1030 date: 1991
1031 nest:
1032 recurse:
1033 - haystack:
1034 needle
1035 the following code snippet would FAIL:
1037 some:
1039 Russian:
1040 dolls
1041 4. With indentation: {spaces: 2, indent-sequences: false}
1043 the following code snippet would PASS:
1045 list:
1047 - flying
1048 - spaghetti
1049 - monster
1050 the following code snippet would FAIL:
1052 list:
1054 - flying
1055 - spaghetti
1056 - monster
1057 5. With indentation: {spaces: 2, indent-sequences: whatever}
1059 the following code snippet would PASS:
1061 list:
1063 - flying:
1064 - spaghetti
1065 - monster
1066 - not flying:
1067 - spaghetti
1068 - sauce
1069 6. With indentation: {spaces: 2, indent-sequences: consistent}
1071 the following code snippet would PASS:
1073 - flying:
1075 - spaghetti
1076 - monster
1077 - not flying:
1078 - spaghetti
1079 - sauce
1080 the following code snippet would FAIL:
1082 - flying:
1084 - spaghetti
1085 - monster
1086 - not flying:
1087 - spaghetti
1088 - sauce
1089 7. With indentation: {spaces: 4, check-multi-line-strings: true}
1091 the following code snippet would PASS:
1093 Blaise Pascal:
1095 Je vous écris une longue lettre parce que
1096 je n'ai pas le temps d'en écrire une courte.
1097 the following code snippet would PASS:
1099 Blaise Pascal: Je vous écris une longue lettre parce que
1101 je n'ai pas le temps d'en écrire une courte.
1102 the following code snippet would FAIL:
1104 Blaise Pascal: Je vous écris une longue lettre parce que
1106 je n'ai pas le temps d'en écrire une courte.
1107 the following code snippet would FAIL:
1109 C code:
1111 void main() {
1112 printf("foo");
1113 }
1114 the following code snippet would PASS:
1116 C code:
1118 void main() {
1119 printf("bar");
1120 }
1121 key-duplicates
1123 Use this rule to prevent multiple entries with the same key in map‐
1124 pings.
1125 Examples
1127 1. With key-duplicates: {}
1129 the following code snippet would PASS:
1131 - key 1: v
1133 key 2: val
1134 key 3: value
1135 - {a: 1, b: 2, c: 3}
1136 the following code snippet would FAIL:
1138 - key 1: v
1140 key 2: val
1141 key 1: value
1142 the following code snippet would FAIL:
1144 - {a: 1, b: 2, b: 3}
1146 the following code snippet would FAIL:
1148 duplicated key: 1
1150 "duplicated key": 2
1151 other duplication: 1
1153 ? >-
1154 other
1155 duplication
1156 : 2
1157 key-ordering
1159 Use this rule to enforce alphabetical ordering of keys in mappings. The
1160 sorting order uses the Unicode code point number. As a result, the
1161 ordering is case-sensitive and not accent-friendly (see examples
1162 below).
1163 Examples
1165 1. With key-ordering: {}
1167 the following code snippet would PASS:
1169 - key 1: v
1171 key 2: val
1172 key 3: value
1173 - {a: 1, b: 2, c: 3}
1174 - T-shirt: 1
1175 T-shirts: 2
1176 t-shirt: 3
1177 t-shirts: 4
1178 - hair: true
1179 hais: true
1180 haïr: true
1181 haïssable: true
1182 the following code snippet would FAIL:
1184 - key 2: v
1186 key 1: val
1187 the following code snippet would FAIL:
1189 - {b: 1, a: 2}
1191 the following code snippet would FAIL:
1193 - T-shirt: 1
1195 t-shirt: 2
1196 T-shirts: 3
1197 t-shirts: 4
1198 the following code snippet would FAIL:
1200 - haïr: true
1202 hais: true
1203 line-length
1205 Use this rule to set a limit to lines length.
1206 Note: with Python 2, the line-length rule may not work properly with
1208 unicode characters because of the way strings are represented in bytes.
1209 We recommend running yamllint with Python 3.
1210 Options
1212 · max defines the maximal (inclusive) length of lines.
1214 · allow-non-breakable-words is used to allow non breakable words (with‐
1216 out spaces inside) to overflow the limit. This is useful for long
1217 URLs, for instance. Use true to allow, false to forbid.
1218 · allow-non-breakable-inline-mappings implies allow-non-breakable-words
1220 and extends it to also allow non-breakable words in inline mappings.
1221 Examples
1223 1. With line-length: {max: 70}
1225 the following code snippet would PASS:
1227 long sentence:
1229 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
1230 eiusmod tempor incididunt ut labore et dolore magna aliqua.
1231 the following code snippet would FAIL:
1233 long sentence:
1235 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
1236 tempor incididunt ut labore et dolore magna aliqua.
1237 2. With line-length: {max: 60, allow-non-breakable-words: true}
1239 the following code snippet would PASS:
1241 this:
1243 is:
1244 - a:
1245 http://localhost/very/very/very/very/very/very/very/very/long/url
1246 # this comment is too long,
1248 # but hard to split:
1249 # http://localhost/another/very/very/very/very/very/very/very/very/long/url
1250 the following code snippet would FAIL:
1252 - this line is waaaaaaaaaaaaaay too long but could be easily split...
1254 and the following code snippet would also FAIL:
1256 - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
1258 3. With line-length: {max: 60, allow-non-breakable-words: true,
1260 allow-non-breakable-inline-mappings: true}
1261 the following code snippet would PASS:
1263 - foobar: http://localhost/very/very/very/very/very/very/very/very/long/url
1265 4. With line-length: {max: 60, allow-non-breakable-words: false}
1267 the following code snippet would FAIL:
1269 this:
1271 is:
1272 - a:
1273 http://localhost/very/very/very/very/very/very/very/very/long/url
1274 new-line-at-end-of-file
1276 Use this rule to require a new line character (\n) at the end of files.
1277 The POSIX standard requires the last line to end with a new line char‐
1279 acter. All UNIX tools expect a new line at the end of files. Most text
1280 editors use this convention too.
1281 new-lines
1283 Use this rule to force the type of new line characters.
1284 Options
1286 · Set type to unix to use UNIX-typed new line characters (\n), or dos
1288 to use DOS-typed new line characters (\r\n).
1289 octal-values
1291 Use this rule to prevent values with octal numbers. In YAML, numbers
1292 that start with 0 are interpreted as octal, but this is not always
1293 wanted. For instance 010 is the city code of Beijing, and should not
1294 be converted to 8.
1295 Examples
1297 1. With octal-values: {forbid-implicit-octal: true}
1299 the following code snippets would PASS:
1301 user:
1303 city-code: '010'
1304 the following code snippets would PASS:
1306 user:
1308 city-code: 010,021
1309 the following code snippets would FAIL:
1311 user:
1313 city-code: 010
1314 2. With octal-values: {forbid-explicit-octal: true}
1316 the following code snippets would PASS:
1318 user:
1320 city-code: '0o10'
1321 the following code snippets would FAIL:
1323 user:
1325 city-code: 0o10
1326 quoted-strings
1328 Use this rule to forbid any string values that are not quoted. You can
1329 also enforce the type of the quote used using the quote-type option
1330 (single, double or any).
1331 Note: Multi-line strings (with | or >) will not be checked.
1333 Examples
1335 1. With quoted-strings: {quote-type: any}
1337 the following code snippet would PASS:
1339 foo: "bar"
1341 bar: 'foo'
1342 number: 123
1343 boolean: true
1344 the following code snippet would FAIL:
1346 foo: bar
1348 trailing-spaces
1350 Use this rule to forbid trailing spaces at the end of lines.
1351 Examples
1353 1. With trailing-spaces: {}
1355 the following code snippet would PASS:
1357 this document doesn't contain
1359 any trailing
1360 spaces
1361 the following code snippet would FAIL:
1363 this document contains
1365 trailing spaces
1366 on lines 1 and 3
1367 truthy
1369 Use this rule to forbid non-explictly typed truthy values other than
1370 allowed ones (by default: true and false), for example YES or off.
1371 This can be useful to prevent surprises from YAML parsers transforming
1373 [yes, FALSE, Off] into [true, false, false] or {y: 1, yes: 2, on: 3,
1374 true: 4, True: 5} into {y: 1, true: 5}.
1375 Options
1377 · allowed-values defines the list of truthy values which will be
1379 ignored during linting. The default is ['true', 'false'], but can be
1380 changed to any list containing: 'TRUE', 'True', 'true', 'FALSE',
1381 'False', 'false', 'YES', 'Yes', 'yes', 'NO', 'No', 'no', 'ON', 'On',
1382 'on', 'OFF', 'Off', 'off'.
1383 Examples
1385 1. With truthy: {}
1387 the following code snippet would PASS:
1389 boolean: true
1391 object: {"True": 1, 1: "True"}
1393 "yes": 1
1395 "on": 2
1396 "True": 3
1397 explicit:
1399 string1: !!str True
1400 string2: !!str yes
1401 string3: !!str off
1402 encoded: !!binary |
1403 True
1404 OFF
1405 pad== # this decodes as 'N»8Qii'
1406 boolean1: !!bool true
1407 boolean2: !!bool "false"
1408 boolean3: !!bool FALSE
1409 boolean4: !!bool True
1410 boolean5: !!bool off
1411 boolean6: !!bool NO
1412 the following code snippet would FAIL:
1414 object: {True: 1, 1: True}
1416 the following code snippet would FAIL:
1418 yes: 1
1420 on: 2
1421 True: 3
1422 2. With truthy: {allowed-values: ["yes", "no"]}
1424 the following code snippet would PASS:
1426 - yes
1428 - no
1429 - "true"
1430 - 'false'
1431 - foo
1432 - bar
1433 the following code snippet would FAIL:
1435 - true
1437 - false
1438 - on
1439 - off
1440 Disable with comments
1442 Disabling checks for a specific line
1443 To prevent yamllint from reporting problems for a specific line, add a
1444 directive comment (# yamllint disable-line ...) on that line, or on the
1445 line above. For instance:
1446 # The following mapping contains the same key twice,
1448 # but I know what I'm doing:
1449 key: value 1
1450 key: value 2 # yamllint disable-line rule:key-duplicates
1451 - This line is waaaaaaaaaay too long but yamllint will not report anything about it. # yamllint disable-line rule:line-length
1453 This line will be checked by yamllint.
1454 or:
1456 # The following mapping contains the same key twice,
1458 # but I know what I'm doing:
1459 key: value 1
1460 # yamllint disable-line rule:key-duplicates
1461 key: value 2
1462 # yamllint disable-line rule:line-length
1464 - This line is waaaaaaaaaay too long but yamllint will not report anything about it.
1465 This line will be checked by yamllint.
1466 It is possible, although not recommend, to disabled all rules for a
1468 specific line:
1469 # yamllint disable-line
1471 - { all : rules ,are disabled for this line}
1472 If you need to disable multiple rules, it is allowed to chain rules
1474 like this: # yamllint disable-line rule:hyphens rule:commas rule:inden‐
1475 tation.
1476 Disabling checks for all (or part of) the file
1478 To prevent yamllint from reporting problems for the whole file, or for
1479 a block of lines within the file, use # yamllint disable ... and # yam‐
1480 llint enable ... directive comments. For instance:
1481 # yamllint disable rule:colons
1483 - Lorem : ipsum
1484 dolor : sit amet,
1485 consectetur : adipiscing elit
1486 # yamllint enable rule:colons
1487 - rest of the document...
1489 It is possible, although not recommend, to disabled all rules:
1491 # yamllint disable
1493 - Lorem :
1494 ipsum:
1495 dolor : [ sit,amet]
1496 - consectetur : adipiscing elit
1497 # yamllint enable
1498 If you need to disable multiple rules, it is allowed to chain rules
1500 like this: # yamllint disable rule:hyphens rule:commas rule:indenta‐
1501 tion.
1502 Development
1504 yamllint provides both a script and a Python module. The latter can be
1505 used to write your own linting tools:
1506 class yamllint.linter.LintProblem(line, column, desc='<no descrip‐
1508 tion>', rule=None)
1509 Represents a linting problem found by yamllint.
1510 column = None
1512 Column on which the problem was found (starting at 1)
1513 desc = None
1515 Human-readable description of the problem
1516 line = None
1518 Line on which the problem was found (starting at 1)
1519 rule = None
1521 Identifier of the rule that detected the problem
1522 yamllint.linter.run(input, conf, filepath=None)
1524 Lints a YAML source.
1525 Returns a generator of LintProblem objects.
1527 Parameters
1529 · input -- buffer, string or stream to read from
1531 · conf -- yamllint configuration object
1533 Integration with text editors
1535 Most text editors support syntax checking and highlighting, to visually
1536 report syntax errors and warnings to the user. yamllint can be used to
1537 syntax-check YAML source, but a bit of configuration is required
1538 depending on your favorite text editor.
1539 Vim
1541 Assuming that the ALE plugin is installed, yamllint is supported by
1542 default. It is automatically enabled when editing YAML files.
1543 If you instead use the syntastic plugin, add this to your .vimrc:
1545 let g:syntastic_yaml_checkers = ['yamllint']
1547 Neovim
1549 Assuming that the neomake plugin is installed, yamllint is supported by
1550 default. It is automatically enabled when editing YAML files.
1551 Emacs
1553 If you are flycheck user, you can use flycheck-yamllint integration.
1554 Other text editors
1556 Help wanted!
1557 Your favorite text editor is not listed here? Help us improve by adding
1559 a section (by opening a pull-request or issue on GitHub).
1560 Integration with other software
1562 Integration with pre-commit
1563 You can integrate yamllint in pre-commit tool. Here is an example, to
1564 add in your .pre-commit-config.yaml
1565 ---
1567 # Update the rev variable with the release version that you want, from the yamllint repo
1568 # You can pass your custom .yamllint with args attribute.
1569 - repo: https://github.com/adrienverge/yamllint.git
1570 rev: v1.17.0
1571 hooks:
1572 - id: yamllint
1573 args: [-c=/path/to/.yamllint]
1574
1576 Adrien Vergé
1577
1579 Copyright 2016, Adrien Vergé
15801.18.0 Oct 15, 2019 YAMLLINT(1)