Project-Local Configuration

Neovim additionally supports project-local configuration via EditorConfig. EditorConfig is a cross-editor configuration framework that was developed to help enforce consistent coding styles in projects with multiple users working on the same code-base, possibly with different editors. However, it provides a simple means of performing some types of configuration, which can make it equally useful for single-user scenarios. Note that EditorConfig supports only a small subset of Neovim's configuration options, although Neovim's implementation provides the ability to extend the supported options.

When a file is opened, Neovim looks for a file named .editorconfig located in the same directory as the file and, if one is found, reads the file and applies any configuration defined in it. After that, Neovim searches upwards through each parent directory and repeats that process. If a .editorconfig is found, it is read and any configuration options defined in it are set, possibly replacing those set from a previously-read .editorconfig file. This allows a single .editorconfig file in a project directory to apply consistent formatting across all projects inside that directory, while also allowing each of those projects to define their own configurations.

.editorconfig files use the INI format, with specific implementation details available on the EditorConfig website. Here is an example .editorconfig file contents:

# specify that this is the top-most EditorConfig file
root = true

# Set defaults for every file
charset = utf-8
end_of_line = lf
insert_final_newline = true

# Use 4 space indentation for all python files
indent_style = space
indent_size = 4

# Use tab indentation for Makefiles
indent_style = tab

# Set indentation for all JS files under the lib directory
indent_style = space
indent_size = 2

Neovim supports the following properties by default:

Property Description
root Set to 'true' to stop Neovim from searching for .editorconfig files in parent directories.
charset Set the 'fileencoding' and 'bomb' options, accepts one of 'utf-8', 'utf-8-bom', 'latin1', 'utf-16be', or 'utf-16le'.
end_of_line Set the end of line character, accepts one of 'lf', 'crlf', or 'cr'.
indent_style Set the 'expandtab' option, accepts one of 'tab' or 'space'.
indent_size Set the 'shiftwidth' and 'softtabstop' options. Accepts a number specifying the width, or 'tab' to use the value assigned to 'tab_stop'.
insert_final_newline 'true' or 'false' to ensure the file always has a trailing newline as its last byte. Sets the 'fixendofline' and 'endofline' options.
max_line_length Set the 'textwidth' option to the specified length.
tab_width Set the 'tabstop' option to the specified width.
trim_trailing_whitespace When 'true', remove trailing whitespace when the buffer is written.