1editorconfig-format(5) File Formats Manual editorconfig-format(5)
2
6 editorconfig-format - EditorConfig File Format
7
9 EditorConfig files use an INI format that is compatible with the format
10 used by Python ConfigParser Library, but [ and ] are allowed in the
11 section names. The section names are filepath globs, similar to the
12 format accepted by gitignore. Forward slashes (/) are used as path
13 separators and semicolons (;) or octothorpes (#) are used for comments.
14 Comments should go individual lines. EditorConfig files should be UTF-8
15 encoded, with either CRLF or LF line separators.
16 Filename globs containing path separators (/) match filepaths in the
18 same way as the filename globs used by .gitignore files. Backslashes
19 (\) are not allowed as path separators.
20 A semicolon character (;) starts a line comment that terminates at the
22 end of the line. Line comments and blank lines are ignored when
23 parsing. Comments may be added to the ends of non-empty lines. An
24 octothorpe character (#) may be used instead of a semicolon to denote
25 the start of a comment.
26
28 When a filename is given to EditorConfig a search is performed in the
29 directory of the given file and all parent directories for an
30 EditorConfig file (named '.editorconfig' by default). All found
31 EditorConfig files are searched for sections with section names
32 matching the given filename. The search will stop if an EditorConfig
33 file is found with the root property set to true or when reaching the
34 root filesystem directory.
35 Files are read top to bottom and the most recent rules found take
37 precedence. If multiple EditorConfig files have matching sections, the
38 rules from the closer EditorConfig file are read last, so properties in
39 closer files take precedence.
40
42 Section names in EditorConfig files are filename globs that support
43 pattern matching through Unix shell-style wildcards. These filename
44 globs recognize the following as special characters for wildcard
45 matching:
46 * Matches any string of characters, except path separators
48 (/)
49 ** Matches any string of characters
51 ? Matches any single character
53 [seq] Matches any single character in seq
55 [!seq] Matches any single character not in seq
57 {s1,s2,s3} Matches any of the strings given (separated by commas, can
59 be nested)
60 {num1..num2} Matches any integer numbers between num1 and num2, where
62 num1 and num2 can be either positive or negative
63 The backslash character () can be used to escape a character so it is
67 not interpreted as a special character.
68 The maximum length of a section name is 4096 characters. All sections
70 exceeding this limit are ignored.
71
73 EditorConfig file sections contain properties, which are name-value
74 pairs separated by an equal sign (=). EditorConfig plugins will ignore
75 unrecognized property names and properties with invalid values.
76 Here is the list of all property names understood by EditorConfig and
78 all valid values for these properties:
79 • indent_style: set to 'tab' or 'space' to use hard tabs or soft tabs
81 respectively. The values are case insensitive.
82 • indent_size: a whole number defining the number of columns used for
83 each indentation level and the width of soft tabs (when supported).
84 If this equals to 'tab', the indent_size will be set to the tab size,
85 which should be tab_width if tab_width is specified, or the tab size
86 set by editor if tab_width is not specified. The values are case
87 insensitive.
88 • tab_width: a whole number defining the number of columns used to
89 represent a tab character. This defaults to the value of indent_size
90 and should not usually need to be specified.
91 • end_of_line: set to 'lf', 'cr', or 'crlf' to control how line breaks
92 are represented. The values are case insensitive.
93 • charset: set to 'latin1', 'utf-8', 'utf-8-bom', 'utf-16be' or
94 'utf-16le' to control the character set. Use of 'utf-8-bom' is
95 discouraged.
96 • trim_trailing_whitespace: set to 'true' to remove any whitespace
97 characters preceeding newline characters and 'false' to ensure it
98 doesn't.
99 • insert_final_newline: set to 'true' ensure file ends with a newline
100 when saving and 'false' to ensure it doesn't.
101 • root: special property that should be specified at the top of the
102 file outside of any sections. Set to 'true' to stop .editorconfig
103 files search on current file. The value is case insensitive.
104 For any property, a value of 'unset' is to remove the effect of that
105 property, even if it has been set before. For example, add 'indent_size
106 = unset' to undefine indent_size property (and use editor default).
107 Property names are case insensitive and all property names are
108 lowercased when parsing. The maximum length of a property name is 50
109 characters and the maximum length of a property value is 255
110 characters. Any property beyond these limits would be ignored.
111EditorConfig Sun Jan 22 2023 editorconfig-format(5)