mstruebing/editorconfig-checker

editorconfig-checker

镜像概述和主要用途

editorconfig-checker 是一个验证文件是否符合 .editorconfig 规则的工具。与仅检查单一文件类型且需要额外配置的工具（如代码检查器）不同，该工具仅需 .editorconfig 即可检查所有文件，确保项目中的文件遵循统一的编码风格。

若您不了解 editorconfig，可访问 editorconfig.org 获取更多信息。

核心功能和特性

支持的 editorconfig 特性

• end_of_line（行尾符）
• insert_final_newline（文件末尾插入空行）
• trim_trailing_whitespace（删除行尾空格）
• indent_style（缩进风格，空格或制表符）
• indent_size（缩进大小）
• max_line_length（最大行长度）

不支持的特性

• charset（字符集）

使用场景和适用范围

适用于需要确保项目中所有文件遵循统一编码风格的场景，包括：

• 开发团队协作时保持代码风格一致
• 代码提交前的自动化风格检查
• 集成到 CI/CD 流程中，确保代码质量
• 多语言项目中统一风格检查，无需为每种语言配置单独工具

详细的使用方法和配置说明

快速开始

shell
VERSION="v3.4.1"
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

安装方法

二进制安装

从 https://github.com/editorconfig-checker/editorconfig-checker/releases 下载对应平台的二进制文件。

Go 安装

若已安装 Go，可执行以下命令：

shell
go get github.com/editorconfig-checker/editorconfig-checker/v3
cd $GOPATH/src/github.com/editorconfig-checker/editorconfig-checker/v3
make build

二进制文件将生成在 bin 目录下，名为 ec。

Arch Linux 安装

通过 pacman 从官方仓库安装：

shell
pacman -S editorconfig-checker

或从 AUR 安装开发版本：

shell
paru -S editorconfig-checker-git  # 使用您偏好的 AUR 助手

Go 全局安装（Go 1.16+）

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

命令行参数

txt
USAGE:
  -config string          指定配置文件路径
  -debug                  打印调试信息
  -disable-end-of-line    禁用行尾符检查
  -disable-indent-size    仅禁用缩进大小检查
  -disable-indentation    禁用缩进风格检查
  -disable-insert-final-newline 禁用文件末尾空行检查
  -disable-trim-trailing-whitespace 禁用行尾空格检查
  -dry-run                显示将被检查的文件，不执行实际检查
  -exclude string         排除文件的正则表达式
  -format                 指定输出格式（default/gcc/github-actions/codeclimate）
  -h                      打印帮助信息
  -help                   打印帮助信息
  -ignore-defaults        忽略默认排除规则
  -init                   创建初始配置文件
  -no-color               禁用彩色输出
  -color                  启用彩色输出
  -v                      打印调试信息
  -verbose                打印调试信息
  -version                打印版本号

输出格式

支持以下输出格式：

• default：纯文本，人类可读格式

  text
  <文件路径>:
    <起始行>-<结束行>: <错误信息>
  

• gcc：GCC 兼容格式，适用于支持语法错误显示的编辑器

  text
  <文件路径>:<行号>:<列号>: <类型>: <错误信息>
  

• github-actions：GitHub Actions 格式

  text
  ::error file=<文件路径>,line=<起始行>,endLine=<结束行>::<错误信息>
  

• codeclimate：Code Climate JSON 格式（用于 GitLab CI 自定义质量报告）

  json
  [
    {
      "check_name": "editorconfig-checker",
      "description": "错误的缩进风格（使用制表符而非空格）",
      "fingerprint": "e87a958a3960d60a11d4b49c563cccd2",
      "severity": "minor",
      "location": {
        "path": ".vscode/extensions.json",
        "lines": {
          "begin": 2,
          "end": 2
        }
      }
    }
  ]
  

配置文件

配置可通过命令行参数或配置文件指定。工具会按以下文件名顺序查找配置文件：

• .editorconfig-checker.json
• .ecrc（已弃用，即将不再支持）

配置文件示例

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
  }
}

• Disable 部分：设置为 true 可禁用对应检查项
• Exclude：排除文件的正则表达式数组
• AllowedContentTypes：添加额外允许的内容类型（默认包含 text/、application/json 等）

可通过 --init 生成初始配置文件，或使用 --config 指定自定义路径。

排除规则

排除行

• 在行尾添加注释 editorconfig-checker-disable-line 排除当前行：

  javascript
  const str = `错误缩进的行`; // editorconfig-checker-disable-line
  

• 使用 editorconfig-checker-disable-next-line 排除下一行：

  javascript
  // editorconfig-checker-disable-next-line 临时排除下一行
  const str = `超长行内容...`;
  

排除块

使用 editorconfig-checker-disable 和 editorconfig-checker-enable 注释包裹需排除的代码块：

javascript
// editorconfig-checker-disable
const str = `
  多行
  错误缩进
`;
// editorconfig-checker-enable

排除路径

内联排除

在文件首行添加注释 editorconfig-checker-disable-file 排除整个文件：

haskell
-- editorconfig-checker-disable-file
add :: Int -> Int -> Int
add x y = x + y  -- 不检查缩进错误

默认排除

工具默认排除以下路径（可通过 --ignore-defaults 禁用）：

• 版本控制相关：.git/、.jj/
• 包管理器文件：package-lock.json、yarn.lock、go.mod 等
• 二进制文件：图片（.png、.jpg）、字体（.ttf、.woff）、压缩包（.zip、.tar.gz）等
• 生成文件：.min.js、.css.map 等

通过配置排除

在配置文件中使用 Exclude 数组添加排除规则：

json
{
  "Exclude": ["test/.*", "\\.md$"]  // 排除 test 目录和 Markdown 文件
}

通过命令行排除

使用 --exclude 参数添加临时排除规则：

shell
ec --exclude "node_modules|\\.log$"

Docker 使用方法

通过 Docker 容器运行工具，需挂载当前目录到容器的 /check 目录：

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

Docker Hub 镜像地址：https://hub.docker.com/r/mstruebing/editorconfig-checker

持续集成 (CI) 集成

Mega-Linter

在 CI 中使用 Mega-Linter 集成 editorconfig-checker，创建 .mega-linter.yml：

yaml
ENABLE:
  - EDITORCONFIG  # 仅启用 editorconfig-checker

GitLab CI

使用 ss-open/ci/recipes 提供的现成 lint 任务，具体配置参见项目文档。

支持与贡献

支持

如有问题或建议，可加入 freenode IRC 频道 #editorconfig-checker，或使用 freenode webchat。

贡献

欢迎提交功能请求、错误报告或代码贡献，贡献指南参见项目 https://github.com/editorconfig-checker/editorconfig-checker/blob/main/CONTRIBUTING.md%E3%80%82

语义化版本策略

• 补丁版本（x.y.Z）：修复错误、性能优化、输出格式调整
• 次要版本（x.Y.z）：新增配置选项、支持新的 editorconfig 特性、添加默认排除规则
• 主要版本（X.y.z）：移除配置选项、不兼容的行为变更、修复导致更多错误被检测的问题