Skip to content
EditorConfig Handbook: One Config File to Unify Indentation, Line Endings & Encoding

EditorConfig Handbook: One Config File to Unify Indentation, Line Endings & Encoding

This guide explains how EditorConfig standardizes editor-level formatting — indentation, line endings, and encoding — across teams, provides a minimal starter config with per-file-type overrides, clarifies its division of labor with Prettier and ESLint, details a three-layer defense for line endings using .gitattributes, and lists five common pitfalls including the unset vs. ignore mistake and inline-comment parsing issues.

Code Farmer Manor Chronicle
Code Farmer Manor Chronicle
Code Farmer Manor Chronicle

What EditorConfig Handles — and What It Doesn't

Mixed tabs vs. spaces, CRLF vs. LF, and UTF-8 with or without BOM are the three most common sources of noisy diffs. They aren't logic bugs, but reviewers must still scan every line to confirm nothing changed. EditorConfig solves this at the source: a .editorconfig file in the project root declares the project's indentation, line-ending, and encoding rules, and supporting editors apply them the moment a file is opened — no shortcuts to remember.

It does not handle code quality. Unused variables, leftover console.log calls, or inconsistent quote styles belong to ESLint and Prettier. The division of labor in one sentence: EditorConfig governs default typing behavior, Prettier governs final format on save, ESLint governs correctness.

Minimal Usable Configuration

Create .editorconfig at the repository root:

# Declare this as the root config; stop searching parent directories
root = true

# Default rules for all files
[*] 
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

# Markdown allows trailing spaces (two spaces = hard line break)
[*.md]
trim_trailing_whitespace = false

Comments must occupy their own line. EditorConfig follows INI format; inline comments are not recognized by many editor implementations and become part of the value, silently breaking rules.

VS Code requires the EditorConfig for VS Code extension (not built-in); it reads the config immediately after install without a restart.

Configuration Options Explained

root — values: true / false; meaning: stop searching upward; treat this file as the root

charset — values: utf-8 / utf-8-bom / latin1; meaning: file encoding; typically utf-8

indent_style — values: space / tab; meaning: whether indentation uses spaces or tabs

indent_size — values: number; meaning: spaces per indent level

tab_width — values: number; meaning: display width of a tab character in spaces

end_of_line — values: lf / crlf / cr; meaning: line-ending style; unify on lf

insert_final_newline — values: true / false; meaning: ensure file ends with a newline

trim_trailing_whitespace — values: true / false; meaning: remove trailing spaces on each line

max_line_length — values: number; meaning: column hint for line length; most editors only warn

insert_final_newline is not pedantry. POSIX defines a text file as ending with a newline; tools like cat, diff, and some build scripts behave inconsistently when it's missing.

Per-File-Type Overrides with Glob Patterns

Brackets accept globs for file-type-specific rules:

root = true

[*] 
indent_style = space
indent_size = 2
end_of_line = lf

# Python convention: 4 spaces
[*.py]
indent_size = 4

# Go uses tabs
[*.go]
indent_style = tab

# Markdown keeps trailing spaces
[*.md]
trim_trailing_whitespace = false

To exclude files (e.g., lock files), use unset , not ignore . unset (supported since EditorConfig 0.15+) cancels an inherited rule. ignore is not a valid value — editors simply discard it, so the rule remains active.

[package-lock.json]
indent_style = unset
indent_size = unset

Common globs: * (any file), *.js (by extension), ** (recursive), {a,b} (alternation).

Line Endings: EditorConfig Alone Is Not Enough

CRLF/LF mismatch is the top cause of red diffs. A three-layer defense is required:

EditorConfig: end_of_line = lf — unifies editor output.

Git layer: .gitattributes with * text=auto eol=lf (or configure core.autocrlf) — governs the bytes that actually enter the repository.

Editor setting: VS Code files.eol = \n — ensures the editor itself writes LF.

Relying only on EditorConfig fails on Windows because Git's default core.autocrlf may convert LF back to CRLF in the working tree, producing "editor writes LF, file stores CRLF" and a fresh wave of red diffs. .gitattributes is the harder layer — it controls repository bytes, while EditorConfig controls editor bytes.

Division of Labor: EditorConfig, Prettier, ESLint

EditorConfig — Responsibility: Editor input defaults (indent, line endings, encoding); Position: Upstream — correct while typing

Prettier — Responsibility: Unified format on save/commit (indent, quotes, semicolons, line width); Position: Format owner — overrides EditorConfig's format rules

ESLint — Responsibility: Code quality (unused vars, potential bugs, best practices); Position: Use eslint-config-prettier to disable its format rules and avoid conflicts

Workflow: EditorConfig → Prettier → ESLint. When rules conflict, Prettier wins because it runs on every save and pre-commit. An EditorConfig indent_size = 2 cannot override Prettier's tabWidth: 4. EditorConfig only affects future keystrokes; it cannot reformat existing code.

Commit all three configs to the repo: .editorconfig + .prettierrc + eslint.config.js. New contributors clone and get consistent editor and CLI behavior instantly — no separate setup doc needed.

Five Common Pitfalls

VS Code plugin installed but no effect: Verify the extension is "EditorConfig for VS Code"; filename must be exactly .editorconfig (leading dot required).

Config changed but no reaction: Some editors need the file reopened; also ensure root = true exists, otherwise a parent directory's config may win.

Using ignore to skip files: No such value. Use unset instead.

Inline comments break rules: Keep comments on their own line.

Line endings still messy: See the three-layer defense above — add .gitattributes, don't rely on EditorConfig alone.

Summary

EditorConfig governs editor input (indent, line endings, encoding); place at root, share with team — it's the upstream link in the code-standard chain.

Comments on separate lines; skip files with unset, not ignore — the two most copied mistakes.

Line-ending fix requires three pieces: EditorConfig + .gitattributes + editor files.eol.

Full loop: .editorconfig (input) → .prettierrc (format) → ESLint (quality) → husky + lint-staged (pre-commit enforcement).

This concludes the 7-part "Frontend Code Standards" series: ESLint + Prettier config, Vue 2/3 project setup, husky hook internals, lint-staged pre-commit checks, Vetur troubleshooting, and EditorConfig input unification. Read in order or bookmark as a configuration reference.

Original Source

Signed-in readers can open the original source through BestHub's protected redirect.

Sign in to view source
Republication Notice

This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactadmin@besthub.devand we will review it promptly.

code-stylevscodeeslintprettiereditorconfigindentationline-endingsgitattributes
Reader feedback

How this landed with the community

Sign in to like

Rate this article

Was this worth your time?

Sign in to rate
Discussion

0 Comments

Thoughtful readers leave field notes, pushback, and hard-won operational detail here.