Introduction (informative)¶

All content in this document is normative unless marked “(informative)”.

EditorConfig helps maintain consistent coding styles for multiple developersworking on the same project across various editors and IDEs. The EditorConfigproject consists of a file format for defining coding styles and a collectionof text editor plugins that enable editors to read the file format and adhereto defined styles. EditorConfig files are easily readable and they work nicelywith version control systems.

Terminology¶

In EditorConfig:

• “EditorConfig files” (named.editorconfig in lowercase) includesection(s) storing key-value pairs. EditorConfig files must conform to thisspecification.

• “Cores” parse files conforming to this specification, and providekey-value pairs to plugins.

• “Plugins” receive key-value pairs from cores and update an editor’ssettings based on the key-value pairs.

• “Editors” permit editing files, and use plugins to update settings forfiles being edited.

A conforming core or plugin must pass the tests in thecore-tests repository orplugin-tests repository, respectively.

(informative) Some plugins include or bundle their own cores, and some relyon external cores. Some editors include or bundle plugin or corefunctionality. Editors, plugins, and cores may all come from differentpeople. Those people may or may not have any direct interaction with theEditorConfig organization.

File Format¶

EditorConfig files are in an INI-like file format.To read an EditorConfig file, take one line at a time, from beginning to end.For each line:

1. Remove all leading and trailing whitespace.

2. Process the remaining text as specified for its type below.

The types of lines are:

• Blank: Contains nothing. Blank lines are ignored.

• Comment: starts with a; or a#. Comment lines are ignored.

• Section Header: starts with a[ and ends with a].These lines define globs; seeGlob Expressions.

  • May contain any characters between the square brackets (e.g.,[ and] and even spaces and tabs are allowed).

  • Forward slashes (/) are used as path separators.

  • Backslashes (\\) are not allowed as path separators (even on Windows).

• Key-Value Pair (or Pair): contains a key and a value, separated by an=.SeeSupported Pairs.

  • Key: The part before the first= on the line.

  • Value: The part, if any, after the first= on the line.

  • Keys and values are trimmed of leading and trailing whitespace, butinclude any whitespace that is between non-whitespace characters.

  • If a value is not provided, then the value is an empty string(i.e.,"" in C or Python).

Any line that is not one of the above is invalid.

EditorConfig files must be UTF-8 encoded, with LF or CRLF line separators.

[*.txt]foo = editorconfig ;)

Glob Expressions¶

Section names in EditorConfig files are filepath globs, similar to the formataccepted by.gitignore. They support pattern matching through Unixshell-style wildcards. These filepath globs recognize the following asspecial characters for wildcard matching:

If the glob contains a path separator (a/ not inside square brackets), then the glob is relativeto the directory level of the particular.editorconfig file itself.Otherwise the pattern may also match at any level below the.editorconfiglevel. For example,*.c matches any file that ends with.c in thedirectory of.editorconfig or any other directory below one that stores this.editorconfig.However, the globsubdir/*.c only matches files that endwith.c in thesubdir directory in the directory of.editorconfig.

Therefore, a leading slash is not relevant if there is already a slash in the middle of the pattern.Thus, the globs/subdir/*.c andsubdir/*.c must yield the same result.

As a corollary, a section name ending with/ does not match any file.

The backslash character (\\) can be used to escape a character so it isnot 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.

File Processing¶

When a filename is given to EditorConfig a search is performed in thedirectory of the given file and all parent directories for an EditorConfigfile. An EditorConfig file is named “.editorconfig”, all lowercased.Non-existing directories are treated as if they exist and are empty. All foundEditorConfig files are searched for sections with section names matching thegiven filename. The search shall stop if an EditorConfig file is found withtheroot key set totrue in the preamble or when reaching the rootfilesystem directory.

Files are read top to bottom and the most recent pairs found takeprecedence. Thus, in case a given file matches multiple sectionswithin a single.editorconfig file, the pairs defined in the section thatcomes later in the.editorconfig file take precedence over pairs definedin the section that comes earlier in the same.editorconfig file.If multiple EditorConfig files have matching sections, the pairsfrom the closer EditorConfig file are read last, so pairs in closerfiles take precedence.

Supported Pairs¶

EditorConfig file sections contain key-value pairs separated by anequal sign (=). With the exception of theroot key, all pairs MUST belocated under a section to take effect.

• EditorConfig cores shall accept and report all syntactically validkey-value pairs, even if the key is not defined in this specification.

• EditorConfig plugins shall ignore unrecognized keys and invalid/unsupportedvalues.

Here is the list of all keys defined by this version of this specification,and the supported values associated with them:

For any pair, a value ofunset removes the effect of thatpair, even if it has been set before. For example, addindent_size=unset to undefine theindent_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.

Indentation (Non-Normative)¶

The indentation related options (indent_style,indent_size andtab_width) require a special documentationsection to specify their behavior. Consider the following code snippet:

defexecute():source="indentation is important"foriinsource.split(" "):print(i)

Theindent_size setting for this code snippet equals 4, becauseindent_size means how many columns are requiredto indent the next line in relation to previous (if indentation, of course, is applicable for this line). Then the next questionishow this indentation of 4 columns is achieved. It may be 4 consequent spaces/soft tabs,a single tab with width equal to 4, or two tabs with width equal to 2.

This is whenindent_style comes into picture. It specifies what character should be usedwhenever possible in order toachieve the indentation size specified inindent_size. To fully understand what “whenever possible” actually means, let’sconsider the following EditorConfig file living in the same directory as the file above:

root=true[example_file.py]indent_style=tabindent_size=4tab_width=3

Theindent_size of 4 is not achievable by placing 1 or 2 consequent tabs, becausetab_width=3. Therefore,in order to comply with this EditorConfig configuration, the new lines (where indentation is applicable)must be preciselyindented with one tab, and one space. That is because by placing one tab we’re not achieving theindent_size required, but byplacing the 2 consequent tabs we’re overreaching. Therefore, althoughindent_style istab, we still have to supplementwith one space character to fulfill the requirement.

For another example, if we have the following EditorConfig file:

root=true[another_file.py]indent_style=tabindent_size=8tab_width=4

OneMUST expect that spaces will not be used at all for indentation, since all the indentation can be achieved via tabs only.

Additionally, it is possible to haveindent_size less than thetab_width.

root=true[another_file.py]indent_style=tabindent_size=4tab_width=8

To understand the way it works, let’s look at the following example:

deffunc():ifTrue:returnTrue

In this case, the line where theif statement condition is specified is indented with 4 spaces, because theindent_size=4and the tab cannot fit in. On the other hand, the line withreturn statement must be indented with one tab, because theindentation level for this line is 8 columns, and a tab can fit in.

Suggestions for Plugin Developers¶

TODO. For now please read thePlugin Guidelines on GitHub wiki.

Versioning¶

This section applies beginning with version 0.14.0 of this specification.

This specification has a version, tagged in thespecification repository.Each specification version corresponds to the same version in thecore-tests repository.

The version numbering of the specification followsSemantic Versioning 2.0.0 (“SemVer”). The version numbering ofthecore-tests repository also follows SemVer.

Each EditorConfig core, to pass the core tests, must process versionnumbers given with the-b switch, and must report version numbers whengiven-v or--version. The version numbers used for-b,-v,and--version are versions of this specification. For example, theVimscript core might respond to-v with:

EditorConfig Vimscript core v1.0.0 - Specification Version 0.14.0

Cores, plugins, or editors supporting EditorConfig have their own versionnumbers. Those version numbers are independent of the version number ofthis specification.