editorconfig-checker

1. What?
2. Quickstart
3. Installation
4. Usage
5. Configuration
6. Excluding
7. Excluding Lines
8. Excluding Blocks
9. Excluding Paths
   1. Inline
   2. Default Excludes
   3. Ignoring Default Excludes
   4. Manually Excluding
      1. via configuration
      2. via arguments
10. Charset Setting
11. Continuous Integration
12. Support
13. Contributing
14. Semantic Versioning Policy

What?

This is a tool to check if your files consider your .editorconfig rules. Most tools—like linters, for example—only test one filetype and need an extra configuration. This tool only needs your .editorconfig to check all files.

If you don't know about editorconfig already you can read about it here: editorconfig.org.

Currently, implemented editorconfig features are:

• end_of_line
• insert_final_newline
• trim_trailing_whitespace
• indent_style
• indent_size
• max_line_length
• charset (see Charset Setting below)

Unsupported features are:

• spelling_language
• tab_width

Quickstart

VERSION="v3.8.0"
OS="linux"
ARCH="amd64"
curl -O -L -C - https://github.com/editorconfig-checker/editorconfig-checker/releases/download/$VERSION/ec-$OS-$ARCH.tar.gz && \
tar xzf ec-$OS-$ARCH.tar.gz && \
./bin/ec-$OS-$ARCH

Installation

You can install editorconfig-checker in several ways, depending on your platform and preferences:

1. Using Go

If you have Go installed, you can install editorconfig-checker with the following command:

go install github.com/editorconfig-checker/editorconfig-checker/v3/cmd/editorconfig-checker@latest

2. Download Prebuilt Binaries

Grab a binary from the release page.

3. Using Nix

If you use Nix:

nix-env -iA nixpkgs.editorconfig-checker

Or, with flakes:

nix run nixpkgs#editorconfig-checker

4. Using Docker

You can run editorconfig-checker inside a Docker container without installing it locally:

docker run --rm --volume=$PWD:/check mstruebing/editorconfig-checker

This command mounts your current directory into the container and runs the check inside it.

See also: Docker Hub: mstruebing/editorconfig-checker

5. Using mise (Polyglot Tool Version Manager)

If you use mise, install with:

mise use -g editorconfig-checker@latest

6. Using Homebrew

If you use Homebrew on macOS or Linux:

brew install editorconfig-checker

7. Arch Linux

• Install from the extra repository: shell pacman -S editorconfig-checker
• Or install the development (VCS) package from the AUR: shell # With your favorite AUR helper, e.g.: paru -S editorconfig-checker-git

Language Specific Wrappers

We do have a couple of language specific wrappers available that you can install with your favorites language package manager. See their respective documentation for installation and usage instructions.

• JavaScript/TypeScript: npm package
• Python: PyPI package
• PHP: Composer package

Usage

USAGE:
  editorconfig-checker [OPTIONS] [FILE...]

With no FILE arguments, all files tracked by git are checked. When one or
more FILE arguments are given, only those files are checked (the configured
exclude patterns still apply).

OPTIONS:
  -color
        enables printing color
  -config string
        config
  -cpuprofile string
        write cpu profile to file
  -debug
        print debugging information
  -disable-charset
        disables only the charset check
  -disable-end-of-line
        disables the trailing whitespace check
  -disable-indent-size
        disables only the indent-size check
  -disable-indentation
        disables the indentation check
  -disable-insert-final-newline
        disables the final newline check
  -disable-max-line-length
        disables only the max-line-length check
  -disable-trim-trailing-whitespace
        disables the trailing whitespace check
  -dry-run
        show which files would be checked
  -exclude string
        a regex which files should be excluded from checking - needs to be a valid regular expression. Combine patterns with | (pipe): -exclude "vendor|testdata"
  -f value
        specify the output format: default, codeclimate, gcc, github-actions (default default)
  -format value
        specify the output format: default, codeclimate, gcc, github-actions (default default)
  -h  print the help
  -help
        print the help
  -ignore-defaults
        ignore default excludes
  -init
        creates an initial configuration
  -no-color
        disables printing color
  -v  print debugging information
  -verbose
        print debugging information
  -version
        print the version number

If you run this tool from a repository root it will check all files which are added to the git repository and are text files. If the tool isn't able to determine a file type it will be added to be checked too.

If you run this tool from a normal directory it will check all files which are text files. If the tool isn't able to determine a file type it will be added to be checked too.

Formats

The following output formats are supported:

• default: Plain text, human readable output.

text <file>: <startingLine>-<endLine>: <message> - gcc: GCC compatible output. Useful for editors that support compiling and showing syntax errors.

<file>:<line>:<column>: <type>: <message> - github-actions: The format used by GitHub Actions

::error file=<file>,line=<startingLine>,endLine=<endingLine>::<message> - codeclimate: The Code Climate json format used for custom quality reports in GitLab CI json [ { "check_name": "editorconfig-checker", "description": "Wrong indent style found (tabs instead of spaces)", "fingerprint": "e87a958a3960d60a11d4b49c563cccd2", "severity": "minor", "location": { "path": ".vscode/extensions.json", "lines": { "begin": 2, "end": 2 } } } ]

Configuration

The configuration is done via arguments or it will take the first config file found with the following file names:

• .editorconfig-checker.json
• .ecrc (deprecated filename, soon unsupported)

A sample configuration file can look like this and will be used from your current working directory if not specified via the --config argument:

{
  "$schema": "https://raw.githubusercontent.com/editorconfig-checker/editorconfig-checker/v3.8.0/.editorconfig-checker.schema.json",
  "Verbose": false,
  "Debug": false,
  "IgnoreDefaults": false,
  "SpacesAfterTabs": false,
  "NoColor": false,
  "Exclude": [],
  "AllowedContentTypes": [],
  "PassedFiles": [],
  "Disable": {
    "EndOfLine": false,
    "Indentation": false,
    "IndentSize": false,
    "InsertFinalNewline": false,
    "TrimTrailingWhitespace": false,
    "MaxLineLength": false,
    "Charset": false
  }
}

The $schema property is an optional field for specifying the JSON Schema and is ignored by editorconfig-checker.

Configuration Keys

Key	Type	Default	Description
Verbose	bool	false	Print verbose output during checking
Debug	bool	false	Print debugging information
IgnoreDefaults	bool	false	Ignore the default exclude patterns
SpacesAfterTabs	bool	false	Allow spaces after tabs in indentation (mixed indentation). When false, spaces following tabs are flagged as errors
NoColor	bool	false	Disable colored output
Exclude	string[]	[]	Regular expressions for files to exclude from checking
AllowedContentTypes	string[]	[]	Additional content types to check (added to the defaults listed below)
PassedFiles	string[]	[]	Explicit list of files, directories, or shell-style glob patterns (e.g. src/*.go) to check. When set, only these paths are checked instead of auto-discovering files from the working directory or git. Glob patterns that don't match any file are left as-is so a subsequent content-type check surfaces the missing path
Version	string	""	When set, the tool verifies this value matches the binary version and exits with an error if they differ. Useful for pinning a specific version in CI
Disable	object		Selectively disable individual checks (see below)

You can set any of the options under the "Disable" section to true to disable those particular checks.

You could also specify command line arguments, and they will get merged with the configuration file. The command line arguments have a higher precedence than the configuration.

You can create a configuration with the init-flag. If you specify a config-path it will be created there.

By default, the allowed_content_types are:

1. text/ (matches text/plain, text/html, etc.)
2. application/ecmascript
3. application/json
4. application/x-ndjson
5. application/xml
6. +json (matches application/geo+json, etc.)
7. +xml (matches application/rss+xml, etc.)
8. application/octet-stream

application/octet-stream is needed as a fallback when no content type could be determined. You can add additional accepted content types with the allowed_content_types key. But the default ones don't get removed.

Excluding

Excluding Lines

You can exclude single lines inline. To do that you need a comment on that line that says: editorconfig-checker-disable-line.

const myTemplateString = `
  first line
     wrongly indented line because it needs to be` // editorconfig-checker-disable-line

Alternatively, you can use editorconfig-checker-disable-next-line to skip the line that comes after this comment. This modifier is present to improve readability, or because your sometimes have no other choice because of your own/language constraints.

// editorconfig-checker-disable-next-line used because blah blah blah what ever the reason blah
const myTemplateString = `a line that is (...) longer (...) than ... usual` // or with a very long inline comment

Please note that using editorconfig-checker-disable-next-line has only an effect on the next line, so it will report if the line where you added the modifier doesn't comply.

Excluding Blocks

To temporarily disable all checks, add a comment containing editorconfig-checker-disable. Re-enable with a comment containing editorconfig-checker-enable

// editorconfig-checker-disable
const myTemplateString = `
  first line
     wrongly indented line because it needs to be
`
// editorconfig-checker-enable

Excluding Paths

You can exclude paths from being checked in several ways:

• ignoring a file by documenting it inside the to-be-excluded file
• adding a regex matching the path to the configuration file
• passing a regex matching the path as argument to --exclude

The --exclude flag accepts a single regular expression. To exclude multiple patterns, combine them using | (regex alternation):

editorconfig-checker --exclude "vendor|testdata|\.min\.js$"

In a configuration file, you can list each pattern as a separate entry in the Exclude array instead:

{
  "Exclude": ["vendor", "testdata", "\\.min\\.js$"]
}

All these excludes are used in addition to the default excludes, unless you [opt out of them](#ignor