This is version 0.16.0 of this specification.
All content in this document is normative unless marked “(informative)”.
EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. The EditorConfig project consists of a file format for defining coding styles and a collection of text editor plugins that enable editors to read the file format and adhere to defined styles. EditorConfig files are easily readable and they work nicely with version control systems.
Changed in version 0.15.1.
“EditorConfig files” (usually named
.editorconfig) include section(s) storing key-value pairs. EditorConfig files must conform to this specification.
“Cores” parse files conforming to this specification, and provide key-value pairs to plugins.
“Plugins” receive key-value pairs from cores and update an editor’s settings based on the key-value pairs.
“Editors” permit editing files, and use plugins to update settings for files being edited.
(informative) Some plugins include or bundle their own cores, and some rely on external cores. Some editors include or bundle plugin or core functionality. Editors, plugins, and cores may all come from different people. Those people may or may not have any direct interaction with the EditorConfig organization.
EditorConfig files are in an INI-like file format. In an EditorConfig file, all beginning whitespace on each line is considered irrelevant. Each line must be one of the following:
Blank: contains only whitespace characters.
Comment: starts with a
- Section Header: starts with a
[and ends with a
May not use any non-whitespace characters outside of the surrounding brackets.
May contain any characters between the square brackets (e.g.,
]and even spaces and tabs are allowed).
Forward slashes (
/) are used as path separators.
\\) are not allowed as path separators (even on Windows).
- Section Header: starts with a
- Key-Value Pair (or Pair): contains a key and a value, separated by an =.
Key: The part before the first = (trimmed of whitespace, but including any whitespace in the middle).
Value: The part after the first = (trimmed of whitespace, but including any whitespace in the middle).
Any line that is not one of the above is invalid.
EditorConfig files should be UTF-8 encoded, with LF or CRLF line separators.
Changed in version 0.15.0.
# anywhere other than at the beginning of a line does not
start a comment, but is part of the text of that line. For example:
foo = editorconfig ;)
foo the value
editorconfig ;) in
not the value
This specification does not define any “escaping” mechanism for
The EditorConfig file format formerly allowed the use of ; and # after the beginning of the line to mark the rest of a line as comment. This led to confusion how to parse values containing those characters. Old EditorConfig parsers may still allow inline comments.
The parts of an EditorConfig file are:
Preamble: the lines that precedes the first section. The preamble is optional and may contain key-value pairs, comments and blank lines.
Section Name: the string between the beginning
[and the ending
Section: the lines starting from a Section Header until the beginning of the next Section Header or the end of the file.
Section names in EditorConfig files are filepath globs, similar to the format
.gitignore. They support pattern matching through Unix
shell-style wildcards. These filepath globs recognize the following as
special characters for wildcard matching:
any string of characters, except path separators (
any string of characters
any single character, except path separators (
any single character in seq
any single character not in seq
any of the strings given (separated by commas, can be nested) (But
any integer numbers between
The backslash character (
\\) can be used to escape a character so it is
not interpreted as a special character.
Cores must accept section names with length up to and including 1024 characters. Beyond that, each implementation may choose to define its own upper limit or no explicit upper limit at all.
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). Non-existing directories are treated
as if they exist and are empty. All found EditorConfig files are
searched for sections with section names matching the given filename. The
search shall stop if an EditorConfig file is found with the
key set to
true in the preamble or when reaching the root
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 pairs in closer files take precedence.
Changed in version 0.16.
EditorConfig file sections contain key-value pairs separated by an
equal sign (
=). With the exception of the
root key, all pairs MUST be
located under a section to take effect.
EditorConfig cores shall accept and report all syntactically valid key-value pairs, even if the key is not defined in this specification.
EditorConfig plugins shall ignore unrecognized keys and invalid/unsupported values.
Here is the list of all keys defined by this version of this specification, and the supported values associated with them:
Set to a whole number defining the number of columns used for each
indentation level and the width of soft tabs (when supported). If this
Set to a whole number defining the number of columns used to represent
a tab character. This defaults to the value of
Sets the natural language that should be used for spell checking. Only one language can be specified. There is no default value.
Note: This property does not specify the charset to be used.
The charset is in separate property
Must be specified in the preamble. Set to
For any pair, a value of
unset removes the effect of that
pair, even if it has been set before. For example, add
unset to undefine the
indent_size pair (and use editor defaults).
Pair keys are case insensitive. All keys are lowercased after parsing.
Cores must accept keys and values with lengths up to and including 1024 and 4096 characters respectively. Beyond that, each implementation may choose to define its own upper limits or no explicit upper limits at all.
TODO. For now please read the Plugin Guidelines on GitHub wiki.
This section applies beginning with version 0.14.0 of this specification.
Each EditorConfig core, to pass the core tests, must process version
numbers given with the
-b switch, and must report version numbers when
--version. The version numbers used for
--version are versions of this specification. For example, the
Vimscript core might respond to
EditorConfig Vimscript core v1.0.0 - Specification Version 0.14.0
Cores, plugins, or editors supporting EditorConfig have their own version numbers. Those version numbers are independent of the version number of this specification.