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

[Discourse]

Discourse 使用 lefthook 来管理 Git hooks，并将 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。

哪些内容会被 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 类型信息的 Glint/TypeScript 风格检查。它在 TypeScript 的 strict 模式下运行，并生成发布的声明文件。

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 Hooks 的关系

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 上建议修改。