EditorConfig Explained: Consistent Settings Across Editors

what is editorconfig

Tired of tabs and spaces fighting across your team’s editors? What is EditorConfig? It’s a small .editorconfig file that tells supported editors your project’s coding style, so everyone formats code the same way.

EditorConfig is one of the helpers covered in the guide to best developer tools.

Item Value
File name .editorconfig (all lowercase)
File format INI-like, UTF-8 encoded, LF or CRLF line separators
Specification version 0.17.2
Section-name length cores must accept Up to and including 1024 characters
Where the file search stops A file with root set to true, or the root filesystem directory

These figures come from the EditorConfig specification and the project’s own site. Specifications change, so check the source before you rely on them.

What EditorConfig does for a team

EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. It has two parts: a file format for defining coding styles, and a collection of text editor plugins that read that format and follow the styles it defines.

The specification names four roles, and knowing them makes the docs easier to read:

  • EditorConfig files hold sections of key-value pairs.
  • Cores parse those files and hand the key-value pairs to plugins.
  • Plugins receive the pairs and update an editor’s settings.
  • Editors are where you actually edit files.

Because the settings live in a plain text file inside your repository, they travel with the code. The project describes these files as easily readable and says they work nicely with version control systems.

What an .editorconfig file looks like

The file uses an INI-like format. Each line is blank, a comment, a section header in square brackets, or a key-value pair separated by an equals sign.

The example on the EditorConfig site sets end-of-line and indentation styles for Python and JavaScript files. In plain terms, it does the following:

  • It starts with root = true, outside any section, to mark the top-most file.
  • Under [*], it sets end_of_line = lf and insert_final_newline = true for every file.
  • Under [*.py], it sets indent_style = space and indent_size = 4.
  • Under [Makefile], it sets indent_style = tab and leaves the size unspecified.
  • Under [lib/**.js], it overrides JavaScript files in the lib directory with indent_style = space and indent_size = 2.

Section names are filepath globs, similar to the format accepted by .gitignore. A glob such as *.py matches Python files, and brace notation such as {package.json,.travis.yml} matches exact file names.

Properties you can set

Every pair in a section uses one of a short list of supported properties. These are the ones listed on the project’s site:

  • indent_style: set to tab or space to use hard tabs or soft tabs.
  • indent_size: a whole number of columns for each indentation level and the width of soft tabs, when supported.
  • tab_width: a whole number of columns used to represent a tab character. It defaults to the value of indent_size and doesn’t usually need to be specified.
  • end_of_line: set to lf, cr, or crlf to control how line breaks are represented.
  • charset: set to latin1 or one of the listed UTF variants, including byte-order-mark and little- or big-endian forms, to control the character set.
  • trim_trailing_whitespace: true removes whitespace before newline characters, and false ensures it doesn’t.
  • insert_final_newline: true ensures the file ends with a newline when saving, and false ensures it doesn’t.
  • root: a special property that belongs at the top of the file, outside any section.

Not every plugin supports every property, so test a new setting in your own editor. Plugins ignore unrecognized property names and properties with invalid values, according to the format documentation, and that same page says using the byte-order-mark variant of UTF is discouraged.

If you leave a property out, your editor’s own settings apply. To cancel a value set earlier, use unset, for example indent_size = unset.

Where files live and which rule wins

When you open a file, EditorConfig searches for a .editorconfig file in that file’s directory and in every parent directory. The specification says the search stops when it finds a file with root set to true in the preamble, or when it reaches the root filesystem directory.

Precedence follows reading order:

  1. Files are read top to bottom, and the most recent pairs found take precedence.
  2. If a file matches several sections in one .editorconfig, the later section wins over the earlier one.
  3. If several .editorconfig files match, the closer file is read last, so its pairs take precedence.

A glob that contains a slash is relative to the directory of the .editorconfig file itself. Otherwise the pattern can match at any level below that directory, so *.c matches C files in nested folders too.

what is editorconfig Laptop closeup
An angled closeup shows a laptop keyboard and a blurred dark screen.

Which editors support EditorConfig?

Support comes in two forms, according to the project’s site. Some editors come bundled with native support, so everything should just work. Others need a plugin.

  • Native support is listed for editors and tools such as Vim, PyCharm, WebStorm, GitHub and GitLab.
  • Plugin required for editors such as Visual Studio Code, Sublime Text, Notepad++ and Eclipse.
  • Headless tools such as Gradle and Maven also need a plugin.

Check the project’s list for your editor before you assume support, because the list can change over time.

Pitfalls to avoid and tools to pair it with

Most problems come from small format details:

  • Inline comments: a semicolon or # that isn’t at the beginning of a line is part of the text of that line, not a comment. The specification notes that old parsers may still allow inline comments, so put comments on their own lines.
  • Backslashes: they are not allowed as path separators, even on Windows. Use forward slashes in section names.
  • Tabs and sizes: when indent_style is tab, you may prefer to leave indent_size unspecified so readers can use their preferred indentation width.
  • Creating the file on Windows: in Windows Explorer, name the file .editorconfig. with a trailing dot, and Explorer renames it for you.

EditorConfig is described as a file format plus editor plugins, so it sets how editors behave while you type and save. To catch problems automatically, many teams add static code analysis tools alongside it.

If you also want checks to run before code is committed, read about how to set up pre-commit hooks and combine the two.

Frequently asked questions

Do I need to install a plugin to use EditorConfig?

Show answer

It depends on your editor. Some editors bundle native support, while others need a plugin, so check the list on the EditorConfig site.

What happens if I don’t set a property?

Show answer

Generally, the editor’s own settings are used, which means EditorConfig takes no effect on that part.

Do I have to add root = true?

Show answer

It isn’t required, but it tells the search where to stop. Without it, the search continues through parent directories until it reaches the root filesystem directory, as described in the specification.

Can a subfolder have its own settings?

Show answer

Yes. Put another .editorconfig in that folder. Because pairs in closer files take precedence, its rules override those in parent folders.