Set up EditorConfig for your Django project

2022-01-14 Let us configure our writing implements to all be the same.

This post is an adapted extract from my book Boost Your Django DX, available now.

The “tabs versus spaces” war is scheduled to rage on until the heat death of the universe. And whilst the Python ecosystem is firmly in the “spaces” camp, there remain numerous other text formatting options.

Inconsistent text formatting between team members can lead to unnecessary editing and even bugs. So it’s best to normalize text formatting in your projects.

EditorConfig is a standard for text editor configuration. It’s built-in to many text editors, such as PyCharm and GitHub’s web editor. For other text editors, you need to install a small plugin, available for nearly every text editor under the sun.

To set up EditorConfig for your project, create a file called .editorconfig the root of your repository. Note the . prefix, which makes the file hidden on Unix systems. The .editorconfig file uses INI file syntax, as parsed by Python’s configparser module.

Here is a .editorconfig file suitable for most Django projects:

# http://editorconfig.org

root = true

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

[*.py]
indent_size = 4

Here’s what this configuration does:

root = true declares that this .editorconfig is the root of the project. This stops the EditorConfig plugins from merging options from any .editorconfig files in parent directories.
The [*] section defines rules for all files. Later, the [*.py] section overridens rules for Python files.
charset = utf-8 says that files should be saved with UTF-8 text encoding. This is the standard encoding for nearly everything, these days.
end_of_line = lf declares that files should use Unix-style LF (Linefeed) newlines ("\n"). Even on Windows, where “CR LF” ("\r\n") is the OS default, it’s best to use LF in code for compatibility.
indent_style = space picks a camp in the “tabs versus spaces” war.
indent_size = 2 determines that one indent level is two spaces. This is the norm for most file formats in Django projects, such as HTML, CSS, JavaScript, JSON, and YAML.
trim_trailing_whitespace = true tells your editor to remove any whitespace (spaces, tabs, etc.) at the end of lines when you press “save”. Trailing whitespace characters normally have no meaning in code, but can lead to annoying “diff noise”. This phenomenon is when a developer changes one part of a file, but trivial edits, like removing trailing whitespace, make it seem like they touched unrelated lines.
insert_final_newline = true ensures that your files end with a newline character, when you press “save”. This is a technical requirement for text files, under POSIX (the standard for Unix operating systems). Most tools can handle text files missing the final newline, but some don’t, even silently skipping the final line, so it’s best to always have it.

(If you use Git, you may even have seen its warning when it encounters a text file without a final newline:
```
$ git diff --cached
diff --git a/example.txt b/example.txt
new file mode 100644
index 0000000..5e1c309
--- /dev/null
+++ b/example.txt
@@ -0,0 +1 @@
+Hello World
\ No newline at end of file
```
…now you know!)
The [*.py] section declares rules specific for .py files. Its only rule switches indentation to four spaces instead of two. This follows the indentation rule in PEP 8, Python’s Style Guide.

Fantastic.

For many projects you should be able to use this .editorconfig file as-is. Unfortunately there’s no easy way to reformat your existing files to match all the rules. But pre-commit has two small tools that can help with particular rules (trailing-whitespace and end-of-file-fixer) [these are described later in the book].

You can customize other file types, or even specific filenames, by adding further sections. For example, to ensure your Makefiles use tabs for indentation:

[Makefile]
indent_style = tab

Cowabunga, your team’s text editors are all in sync!

😸😸😸 Check out my new book on using GitHub effectively, Boost Your GitHub DX! 😸😸😸

One summary email a week, no spam, I pinky promise.

Related posts:

Tags: django