pre-commit

PreCommit

用于管理 pre-commit 钩子的综合技能——这是一个多语言预提交钩子管理框架，可自动执行代码质量检查、格式化、Lint 和安全扫描。

快速参考

命令	说明
pre-commit install	安装 git 钩子
pre-commit run --all-files	对所有文件运行所有钩子
pre-commit autoupdate	将钩子更新到最新版本
pre-commit run <hook-id>	运行指定钩子

工作流路由

工作流	触发条件	文件
Setup	“设置 pre-commit”、“初始化钩子”、“创建配置”	Workflows/Setup.md
AddHooks	“添加钩子”、“添加 Lint”、“添加格式化工具”、“添加安全检查”	Workflows/AddHooks.md
Troubleshoot	“修复 pre-commit”、“钩子运行失败”、“调试钩子”	Workflows/Troubleshoot.md
CIIntegration	“CI 流水线”、“GitHub Actions”、“GitLab CI”	Workflows/CIIntegration.md
CustomHook	“创建自定义钩子”、“本地钩子”、“编写钩子”	Workflows/CustomHook.md

文档

文档	用途
QuickStartGuide.md	安装和首次设置
HooksReference.md	按语言／用途分类的综合钩子目录
ConfigurationGuide.md	高级配置选项
SecurityHooks.md	密钥检测和安全扫描

工具

工具	用途
Tools/PreCommitManager.ts	用于管理 pre-commit 配置的 CLI
Tools/HookGenerator.ts	生成 .pre-commit-config.yaml 模板
Tools/HookValidator.ts	验证钩子配置

示例

示例 1：为新项目设置 pre-commit

User: "Setup pre-commit for my Python project"
→ Invokes Setup workflow
→ Creates .pre-commit-config.yaml with Python hooks (black, isort, flake8)
→ Runs pre-commit install

示例 2：添加 Terraform 钩子

User: "Add Terraform validation hooks"
→ Invokes AddHooks workflow
→ Adds terraform_fmt, terraform_validate, terraform_docs hooks
→ Configures tflint and checkov integration

示例 3：添加安全扫描

User: "Add secret detection to pre-commit"
→ Invokes AddHooks workflow
→ Adds gitleaks, detect-secrets, trufflehog hooks
→ Configures appropriate exclusion patterns

示例 4：调试运行失败的钩子

User: "My eslint pre-commit hook is failing"
→ Invokes Troubleshoot workflow
→ Checks hook configuration and dependencies
→ Provides fix recommendations

支持的钩子类别

• Python：black、isort、flake8、mypy、bandit、pyupgrade
• JavaScript/TypeScript：prettier、eslint、biome
• 基础设施：terraform、terragrunt、helm、kustomize
• Kubernetes：kubeconform、kubeval、checkov
• 安全：gitleaks、detect-secrets、trufflehog、trivy
• 通用：yamllint、jsonlint、shellcheck、markdownlint

---

注意事项

• 在编辑器终端中通过 git commit -m 运行时，钩子输出会消失 — 编辑器封装会吞掉 stdout/stderr。直接运行 pre-commit run --all-files，查看实际失败消息。
• pre-commit autoupdate 会升级到最新标签，但不会更新钩子仓库中固定的配置 — 内部固定 flake8==6.0.0 的钩子仍会使用该版本。运行 autoupdate 后，请检查各个钩子的 additional_dependencies。
• 默认情况下，钩子只会对暂存文件运行，因此在 git add 后编辑文件再提交时，钩子检查的是旧内容。在 CI 中使用 --all-files 来避免遗漏。
• exclude: 正则表达式的锚定方式与 files: 不同 — 在某些钩子版本中，exclude: tests/ 不会排除 tests/foo.py；请使用 exclude: ^tests/ 以确保安全。所有模式都应明确锚定。
• language: system 钩子会绕过 pre-commit 虚拟环境，并依赖用户的 PATH — 在本机上能运行，在 CI 中却会因 command not found 而失败。建议使用带有 additional_dependencies 的 language: python。
• 默认情况下，pre-commit install 不会为 commit-msg 或 pre-push 安装钩子 — 需要单独调用 --hook-type。许多团队添加了 commit-msg 钩子后，才发现它们根本不会触发。
• 通过 SKIP=hookid git commit 跳过钩子仅对当前 Shell 调用有效，而非针对某次提交 — CI 会在全新的环境中运行，未设置 SKIP，因此钩子仍会触发。