Set up EditorConfig for Your Django Project
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 = truedeclares that this
.editorconfigis the root of the project. This stops the EditorConfig plugins from merging options from any
.editorconfigfiles in parent directories.
[*]section defines rules for all files. Later, the
[*.py]section overridens rules for Python files.
charset = utf-8says that files should be saved with UTF-8 text encoding. This is the standard encoding for nearly everything, these days.
end_of_line = lfdeclares 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 = spacepicks a camp in the “tabs versus spaces” war.
trim_trailing_whitespace = truetells 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 = trueensures 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!)
[*.py]section declares rules specific for
.pyfiles. Its only rule switches indentation to four spaces instead of two. This follows the indentation rule in PEP 8, Python’s Style Guide.
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 (
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!
Learn how to make your tests run quickly in my book Speed Up Your Django Tests.
One summary email a week, no spam, I pinky promise.