NAME¶
editorconfig-format - EditorConfig File Format
EditorConfig files use an INI file format in which section names are globs
matching filenames in a format accepted by the fnmatch C library.
Filename globs containing path separators (/) match filepaths in the same way as
the filename globs used by .gitignore files. Backslashes (\) are not allowed
as path separators.
A semicolon character (;) starts a line comment that terminates at the end of
the line. Line comments and blank lines are ignored when parsing. Comments may
be added to the ends of non-empty lines. An octothorpe character (#) may be
used instead of a semicolon to denote the start of a comment.
EditorConfig files should be UTF-8 encoded, with either CRLF or LF line
separators.
Filename and Location¶
When a filename is given to EditorConfig a search is performed in the directory
of the given file and all parent directories for an EditorConfig file (named
'.editorconfig' by default). All found EditorConfig files are searched for
sections with section names matching the given filename. The search will stop
if an EditorConfig file is found with the root property set to true or when
reaching the root filesystem directory.
Files are read top to bottom and the most recent rules found take precedence. If
multiple EditorConfig files have matching sections, the rules from the closer
EditorConfig file are read last, so properties in closer files take
precedence.
Wildcard Patterns¶
Section names in EditorConfig files are filename globs that support pattern
matching through Unix shell-style wildcards. These filename globs recognize
the following as special characters for wildcard matching:
* Matches any string of characters, except path separators (/)
** Matches any string of characters
? Matches any single character
[seq] Matches any single character in seq
[!seq] Matches any single character not in seq
{s1,s2,s3} Matches any of the strings given (separated by commas)
The backslash character () can be used to escape a character so it is not
interpreted as a special character.
Supported Properties¶
EditorConfig file sections contain properties, which are name-value pairs
separated by an equal sign (=). EditorConfig plugins will ignore unrecognized
property names and properties with invalid values.
Here is the list of all property names understood by EditorConfig and all valid
values for these properties:
- •
- indent_style: set to 'tab' or 'space' to use hard tabs or soft tabs
respectively. The values are case insensitive.
- •
- indent_size: a whole number defining the number of columns used for
each indentation level and the width of soft tabs (when supported). If
this equals to 'tab', the indent_size will be set to the tab size,
which should be tab_width if tab_width is specified, or the tab
size set by editor if tab_width is not specified. The values are
case insensitive.
- •
- tab_width: a whole number defining the number of columns used to
represent a tab character. This defaults to the value of
indent_size and should not usually need to be specified.
- •
- end_of_line: set to 'lf', 'cr', or 'crlf' to control how line
breaks are represented. The values are case insensitive.
- •
- charset: set to 'latin1', 'utf-8', 'utf-8-bom', 'utf-16be' or
'utf-16le' to control the character set. Use of 'utf-8-bom' is
discouraged.
- •
- trim_trailing_whitespace: set to 'true' to remove any whitespace
characters preceding newline characters and 'false' to ensure it
doesn't.
- •
- insert_final_newline: set to 'true' ensure file ends with a newline
when saving and 'false' to ensure it doesn't.
- •
- root: special property that should be specified at the top of the
file outside of any sections. Set to 'true' to stop .editorconfig files
search on current file. The value is case insensitive.
Property names are case insensitive and all property names are lowercased when
parsing.