ln-742-precommit-setup

**路径：**文件路径（references/、../ln-*）均相对于此技能目录。

ln-742-precommit-setup

**类型：**L3 Worker **类别：**7XX 项目引导

设置 Git 钩子，在提交前自动执行代码质量检查。

---

目的与范围

会执行：

• 安装钩子管理工具（Husky 或 pre-commit）
• 配置暂存文件检查（lint-staged 或 pre-commit 钩子）
• 设置提交信息验证（commitlint）
• 验证钩子是否能正确触发

不会执行：

• 配置代码检查工具本身（由 ln-741 执行）
• 设置测试基础设施（由 ln-743 执行）
• 修改源代码

---

支持的技术栈

技术	钩子管理器	暂存检查	提交验证
Node.js	Husky	lint-staged	commitlint
Python	pre-commit	pre-commit 钩子	pre-commit 钩子
混合	两者（如有需要）	特定技术栈	commitlint

---

阶段 1：检查现有钩子

安装前，检查是否已有钩子配置。

要检查的文件：

工具	标识
Husky	.husky/ 目录、package.json 中的 husky
pre-commit	.pre-commit-config.yaml
lint-staged	package.json 中的 lint-staged 或 .lintstagedrc*
commitlint	commitlint.config.*、.commitlintrc*

决策逻辑：

1. 如果钩子已存在且正常工作：跳过（告知用户）
2. 如果只完成了部分设置：询问用户是要完成设置还是替换现有设置
3. 如果没有钩子：根据模板创建

---

阶段 2：安装钩子管理器

Node.js 项目（Husky）

npm install -D husky
npx husky init

这会创建：

• .husky/ 目录
• .husky/pre-commit 钩子文件
• 在 package.json 中添加 prepare 脚本

Python 项目（pre-commit）

pip install pre-commit
# OR with uv:
uv add --dev pre-commit

pre-commit install

这会创建：

• .git/hooks/pre-commit（由 pre-commit 管理）
• 需要 .pre-commit-config.yaml 作为配置文件

---

阶段 3：配置暂存文件检查

Node.js（lint-staged）

npm install -D lint-staged

创建配置（.lintstagedrc.mjs 或在 package.json 中配置）：

主要规则：

• TypeScript 文件：ESLint + Prettier
• JSON/MD/CSS：仅 Prettier
• C# 文件：dotnet format（如果是混合项目）

**关键修正：**对于 .NET 文件，请使用正确的语法： "*.cs": "dotnet format --include" 是错误的 使用："*.cs": "dotnet format whitespace --include"，或单独运行 dotnet format

Python（pre-commit 钩子）

在 .pre-commit-config.yaml 中配置：

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

---

阶段 4：配置提交信息验证

Node.js（commitlint）

npm install -D @commitlint/cli @commitlint/config-conventional

创建 commitlint.config.mjs，包含：

• Conventional Commits 格式
• 允许的类型：feat、fix、docs、style、refactor、test、chore、ci
• 标题最大长度：100 个字符

更新 Husky 钩子

添加 commit-msg 钩子：

echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

Python（用于验证提交信息的 pre-commit 钩子）

添加到 .pre-commit-config.yaml：

  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.4.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]

---

阶段 5：测试钩子

验证钩子是否能正常工作。

测试 1：lint-staged 是否触发

# Create a file with lint issues
echo "const x=1" > test-file.ts
git add test-file.ts
git commit -m "test: verify hooks"
# Expected: lint-staged runs, either fixes or blocks

测试 2：提交信息验证

git commit --allow-empty -m "bad message"
# Expected: commitlint rejects

git commit --allow-empty -m "test: valid message format"
# Expected: commit succeeds

清理：

rm test-file.ts
git reset HEAD~1  # If test commit was made

---

关键规则

**规则 1：**Husky 要求 Git 仓库已初始化（先运行 git init）。

**规则 2：**必须先配置好 lint-staged 使用的代码检查工具（运行 ln-741，再运行 ln-742）。

**规则 3：**应说明紧急提交时可使用 --no-verify 跳过检查。

**规则 4：**pre-commit 钩子应尽可能自动修复（使用 --fix 标志）。

---

**监控（2.1.98+）：**钩子验证调用预计耗时超过 30 秒的 lint/test 命令时，请使用 Monitor。备用方案：Bash(run_in_background=true)。

完成标准

• 已安装钩子管理器（Husky 或 pre-commit）
• 已配置暂存文件检查且正常工作
• 已配置提交信息验证
• 测试提交可正确触发钩子
• 已告知用户：
  • 钩子的工作方式
  • 如何在紧急情况下跳过钩子（git commit --no-verify）
  • 要求的提交信息格式

Reference Files

File	Purpose
husky_precommit_template.sh	Husky pre-commit hook
husky_commitmsg_template.sh	Husky commit-msg hook
lintstaged_template.mjs	lint-staged configuration
commitlint_template.mjs	commitlint configuration
precommit_config_template.yaml	Python pre-commit config
hooks_guide.md	Detailed hooks guide

---

Error Handling

Error	Cause	Resolution
Husky not running	Missing prepare script	Run npx husky init again
lint-staged fails	Missing linter	Run ln-741 first
pre-commit not found	Not in PATH	pip install pre-commit
Hooks not triggering	Git hooks disabled	Check .git/hooks/ permissions
Windows path issues	Shell script format	Use cross-platform syntax

---

Emergency Bypass

Document for users:

# Skip all hooks (use sparingly!)
git commit --no-verify -m "emergency: bypass hooks"

# Skip only pre-commit (keeps commit-msg)
HUSKY=0 git commit -m "fix: urgent hotfix"

---

Version: 2.0.0 Last Updated: 2026-01-10