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

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

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

Markdown 文档文件目前不属于 bin/lint 的检查范围，因此运行 bin/lint path/to/doc.md 会报告没有匹配的文件可供检查。

检查范围

具体配置位于 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 代码检查

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

检查工具：

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

SCSS 代码检查

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

检查工具：

• stylelint

YAML 和区域设置（Locale）检查

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

检查工具：

• yaml-lint
• script/i18n_lint.rb

类型检查

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

• pnpm lint:types

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

bin/lint path/to/file 和 pre-commit 钩子不会运行完整的类型检查。如果你想要完整的仓库级检查，请使用不带参数的 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 检查
• Glint/类型检查

与 git 钩子的关系

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

这意味着：

• 提交可能会因为已暂存的文件未通过代码检查而失败
• 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

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

---

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