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

[Discourse]

Discourse 使用 lefthook 来处理 git hook，并使用 bin/lint 作为手动运行相同检查的主要命令行入口点。

如果你在本地克隆中工作，请安装一次 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: lint 最近 50 次提交中更改的文件，以及未跟踪的文件
• bin/lint --staged: 只 lint 暂存的文件
• bin/lint --unstaged: 只 lint 未暂存的文件
• bin/lint --wip: lint 暂存的文件、未暂存的文件以及自 main 以来更改的文件
• 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 linting

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

检查项：

• eslint

GJS 模板 linting

• frontend/**/*.gjs
• 匹配的插件和主题 .gjs 文件

检查项：

• ember-template-lint

SCSS linting

• 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 时，还会运行全仓库的 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
• ember-template-lint --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 linting
• Glint/类型检查

与 git hooks 的关系

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

这意味着：

• 如果暂存的文件不通过 linting，提交可能会失败
• 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 上建议更改。