Introduction

Maintaining consistent code formatting across different editors and IDEs is a common challenge in software development, especially in team environments. EditorConfig provides a simple solution to this problem by defining coding styles that are automatically applied by supported editors. This comprehensive reference guide covers everything you need to know about EditorConfig, from basic usage to advanced configurations and IDE compatibility.

What is EditorConfig?

EditorConfig is a file format and collection of text editor plugins that enable developers to define and maintain consistent coding styles between different editors and IDEs. The EditorConfig project consists of:

• A file format specification for .editorconfig files
• Plugins for various text editors and IDEs
• A core library that parses the file format

EditorConfig helps maintain consistent coding styles across your entire codebase regardless of which editor or IDE your team members use. It works by creating a configuration file that defines coding styles and is read by EditorConfig plugins when files are opened in supported editors.

File Format

EditorConfig files use an INI-like format with sections and properties. The file should be named .editorconfig and can be placed in any directory in your project. EditorConfig files are read from top to bottom, with the closest file to the edited file taking precedence.

# EditorConfig is awesome: https://EditorConfig.org

# top-most EditorConfig file
root = true

# Unix-style newlines with a newline ending every file
[*]
end_of_line = lf
insert_final_newline = true
charset = utf-8
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

# 4 space indentation for Python files
[*.py]
indent_size = 4

# Tab indentation for Makefiles
[Makefile]
indent_style = tab

# Markdown files
[*.md]
trim_trailing_whitespace = false

The file format consists of:

• Sections: Defined by patterns in square brackets like [*.js]
• Properties: Key-value pairs like{" "} indent_style = space
• Comments: Lines starting with # or{" "} ;

Core Properties

EditorConfig defines several core properties that are supported by most editors with EditorConfig plugins.

indent_style

Sets the indentation style to use: tab or{" "} space.

indent_style = space  # Use spaces for indentation
# OR
indent_style = tab    # Use tabs for indentation

indent_size

Sets the number of columns used for each indentation level. Must be a positive integer.

indent_size = 2  # Use 2 spaces/columns per indentation level
# OR
indent_size = 4  # Use 4 spaces/columns per indentation level

tab_width

Sets the width of tab characters. If not specified,{" "} tab_width defaults to the value of{" "} indent_size.

tab_width = 4  # A tab is equivalent to 4 spaces

end_of_line

Sets the line ending format: lf (Unix),{" "} cr (Mac), or crlf (Windows).

end_of_line = lf    # Unix-style line endings (\\n)
# OR
end_of_line = crlf  # Windows-style line endings (\\r\\n)
# OR
end_of_line = cr    # Classic Mac-style line endings (\\r)

charset

Sets the character encoding for the file: latin1,{" "} utf-8, utf-8-bom, utf-16be, or utf-16le.

charset = utf-8  # Use UTF-8 encoding without BOM
# OR
charset = utf-8-bom  # Use UTF-8 encoding with BOM

trim_trailing_whitespace

Sets whether trailing whitespace should be trimmed when saving a file: true or false.

trim_trailing_whitespace = true   # Remove trailing whitespace
# OR
trim_trailing_whitespace = false  # Preserve trailing whitespace

insert_final_newline

Sets whether files should end with a newline: true or{" "} false.

insert_final_newline = true   # Ensure file ends with a newline
# OR
insert_final_newline = false  # No newline at end of file

max_line_length

Sets the maximum line length. Must be a positive integer or{" "} off to disable.

max_line_length = 80    # Limit lines to 80 characters
# OR
max_line_length = 100   # Limit lines to 100 characters
# OR
max_line_length = off   # No line length limit

Extended Properties

Some editors support additional properties beyond the core set. These are not standardized and may vary between editors.

IDE Compatibility

EditorConfig is supported by many popular editors and IDEs, either natively or through plugins. Here's a detailed compatibility matrix for the most common editors:

Visual Studio Code

Visual Studio Code has built-in support for EditorConfig. No plugin installation is required.

• Supports all core properties
• Applies settings immediately when files are opened
• Shows the active EditorConfig settings in the status bar

JetBrains IDEs

JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm, etc.) have built-in support for EditorConfig.

• Supports all core properties
• Provides additional properties for language-specific formatting
• Integrates with the IDE's code style settings

Sublime Text

Sublime Text requires the EditorConfig plugin to be installed via Package Control.

# Install via Package Control
# 1. Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
# 2. Type "Package Control: Install Package"
# 3. Search for "EditorConfig" and install

Atom

Atom requires the EditorConfig plugin to be installed.

# Install via Atom's package manager
apm install editorconfig

Note: Atom has been discontinued, but the plugin still works for existing installations.

Vim

Vim requires the EditorConfig plugin to be installed.

# Install with Vim-Plug
Plug 'editorconfig/editorconfig-vim'

# Or with Vundle
Plugin 'editorconfig/editorconfig-vim'

# Or with Pathogen
cd ~/.vim/bundle
git clone https://github.com/editorconfig/editorconfig-vim.git

Emacs

Emacs requires the EditorConfig plugin to be installed.

; Install with package.el
(package-install 'editorconfig)

; Add to your init.el
(require 'editorconfig)
(editorconfig-mode 1)

Visual Studio

Visual Studio 2017 and later have built-in support for EditorConfig. For earlier versions, an extension is required.

• Supports all core properties
• Provides additional properties specific to C# and Visual Basic
• Integrates with Visual Studio's text editor settings

Language-Specific Settings

EditorConfig allows you to specify different settings for different file types. Here are some common language-specific configurations:

Go

Go has very opinionated formatting rules enforced by{" "} gofmt.

[*.go]
indent_style = tab
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

Ruby

[*.rb]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

PHP

[*.php]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

Real-World Examples

Here are some examples of EditorConfig files from popular open-source projects:

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
max_line_length = 80

[*.md]
trim_trailing_whitespace = false

root = true

[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.{html,css,scss,js,json,yml}]
indent_size = 2

[*.md]
trim_trailing_whitespace = false

root = true

[*]
indent_style = tab
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true

[*.{json,yml,md,bowerrc,eslintrc,js,ts}]
indent_style = space
indent_size = 2

[*.md]
trim_trailing_whitespace = false

Troubleshooting

Here are some common issues and their solutions:

Conclusion

EditorConfig provides a simple, cross-platform solution for maintaining consistent coding styles across different editors and IDEs. By using EditorConfig, teams can:

• Enforce consistent coding styles
• Reduce formatting-related merge conflicts
• Improve code readability
• Onboard new team members more quickly
• Focus on writing code rather than debating formatting

While EditorConfig doesn't solve all code style issues, it provides a solid foundation for basic formatting consistency. For more advanced formatting needs, consider combining EditorConfig with language-specific formatters like Prettier, Black, or gofmt.