提交前自动执行代码检查和格式化

[Discourse]

Discourse 使用 lefthook 来管理 Git 钩子，并将 bin/lint 作为手动运行相同检查的主要 CLI 入口点。

如果你在本地克隆仓库中工作，请安装一次钩子：

pnpm install
pnpm lefthook install

之后，在 git commit 时，已暂存的文件将自动进行检查。

主要命令：bin/lint

当你希望手动运行仓库中配置的 linter，而不是等待 pre-commit 钩子时，请使用 bin/lint。

常见示例：

bin/lint
bin/lint path/to/file.rb path/to/file.gjs
bin/lint --recent
bin/lint --staged
bin/lint --unstaged
bin/lint --wip
bin/lint --fix path/to/file.rb
bin/lint --fix --recent
bin/lint --fix

每种模式的作用

• bin/lint：对仓库中所有受支持的文件进行 lint 检查
• bin/lint path/to/file ...：仅对指定的文件进行 lint 检查
• bin/lint --recent：对最近 50 次提交中更改的文件以及未跟踪的文件进行 lint 检查
• bin/lint --staged：仅对已暂存的文件进行 lint 检查
• bin/lint --unstaged：仅对未暂存的文件进行 lint 检查
• bin/lint --wip：对已暂存的文件、未暂存的文件以及自 main 分支以来更改的文件进行 lint 检查
• bin/lint --fix ...：对选定的文件运行自动修复工具
• bin/lint --fix：在整个仓库中运行所有可用的自动修复工具
• bin/lint --verbose：打印底层的 lefthook 命令

当你传入明确的文件时，bin/lint 会在调用 lefthook 之前将它们过滤为受支持的、可 lint 的文件类型。

Markdown 文件仅在 docs/developer-guides/ 目录下进行 lint 检查。在其他任何 Markdown 文件上运行 bin/lint path/to/doc.md 都会报告没有进行 lint 检查。

哪些内容会被检查

具体配置位于 lefthook.yml。在撰写本文时，bin/lint 涵盖以下内容：

Ruby

• **/*.{rb,rake,thor}
• bin/**/* 下的 Ruby 脚本
• Gemfile

检查项：

• rubocop
• syntax_tree (stree check)

JavaScript、GJS、CSS 和 SCSS 格式化

• app/assets/stylesheets/**/*.{css,scss}
• frontend/**/*.{js,gjs,scss,css,cjs,mjs}
• 匹配的插件和主题资源文件

检查项：

• prettier/pprettier

JavaScript 和 GJS lint 检查

• frontend/**/*.{js,gjs}
• 匹配的插件和主题 JS 文件

检查项：

• eslint（包含 eslint-plugin-ember 的 template-* 规则，用于覆盖 .gjs 文件的模板部分）

SCSS lint 检查

• app/assets/stylesheets/**/*.scss
• 匹配的插件和主题 SCSS 文件

检查项：

• stylelint

YAML 和语言环境检查

• **/*.{yaml,yml}，但不包括 config/database.yml
• **/{client,server}.en.yml

检查项：

• yaml-lint
• script/i18n_lint.rb

类型检查

当你不带文件参数运行 bin/lint 时，全仓库 lint 还会运行：

• pnpm lint:types

这是针对 Discourse JavaScript 类型信息的 Glint/TypeScript 风格检查。

bin/lint path/to/file 和 pre-commit 钩子不会运行完整的类型检查。如果你想要完整的仓库级 lint 检查，请使用普通的 bin/lint。

哪些可以自动修复

bin/lint --fix 可以自动修复许多问题，但并非所有问题。

自动修复配置用于：

• prettier --write
• eslint --fix
• stylelint --fix
• rubocop -A
• syntax_tree (stree write)

实际上，这意味着 --fix 可以重新格式化和重写：

• Ruby
• JavaScript / GJS
• CSS / SCSS

以下检查不能通过 bin/lint --fix 自动修复：

• YAML 语法验证
• client.en.yml / server.en.yml 的 i18n lint 检查
• Glint/类型检查

与 Git 钩子的关系

Pre-commit 钩子使用与 bin/lint 相同的 lefthook 配置，但它仅针对已暂存的文件运行。

这意味着：

• 如果已暂存的文件未通过 lint 检查，提交可能会失败
• bin/lint --staged 是与 pre-commit 钩子最接近的手动等效命令
• bin/lint --fix --staged 是修复你即将提交的内容的好方法

实际工作流

对于日常开发，以下是最有用的命令：

# 在提交几个更改的文件之前
bin/lint --fix path/to/file1.rb path/to/file2.gjs

# 检查 pre-commit 钩子将检查的确切内容
bin/lint --staged

# 清理所有当前进行中的工作
bin/lint --fix --wip

# 运行完整的仓库 lint 套件，包括类型检查
bin/lint

---

本文档受版本控制 - 请在 github 上建议更改。