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

[Discourse]

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

如果你在本地克隆中工作，只需安装一次 hooks：

pnpm install
pnpm lefthook install

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

主要命令：bin/lint

当你想手动运行仓库中配置的 linter 而不等待 pre-commit hook 时，请使用 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 文档文件目前不包含在 bin/lint 中，因此运行 bin/lint path/to/doc.md 会报告没有匹配的文件可供 lint 检查。

哪些内容会被 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 hook 不会运行完整的类型检查。如果你希望进行完整的仓库级 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 hooks 的关系

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

这意味着：

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

实际工作流程

在日常开发中，以下命令最有用：

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

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

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

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

---

本文档受版本控制 - 可在 GitHub 上提出修改建议。