chore: migrate hooks to pre-commit

Author: Charliechen114514

.githooks/pre-commit

@@ -1,37 +1,48 @@
-# Optional pre-commit framework checks.
-# The default one-step commit automation lives in .githooks/pre-commit.
-# Install the native Git hook with: pnpm hooks:install
-
-repos:
-  # Markdown linting
-  - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.38.0
-    hooks:
-      - id: markdownlint
-        args: ['--config', '.markdownlint.json']
-        files: '^documents/.*\.md$'
-        exclude: '^documents/.*\bindex\.md$'
-
-  # Frontmatter validation (local hook)
-  - repo: local
-    hooks:
-      - id: validate-frontmatter
-        name: Validate article frontmatter
-        entry: scripts/validate_frontmatter.py
-        language: python
-        additional_dependencies: ['pyyaml']
-        files: '^documents/core-embedded-cpp/.*\.md$'
-        exclude: '(index\.md|tags\.md)$'
-        pass_filenames: false
-
-  # Check for added large files
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
-    hooks:
-      - id: check-added-large-files
-        args: ['--maxkb=1500']
-      - id: end-of-file-fixer
-      - id: trailing-whitespace
-        files: '^documents/.*\.md$'
-      - id: check-yaml
-        files: '^\.github/.*\.ya?ml$'
+# Install with: pnpm hooks:install
+
+repos:
+  # Markdown linting
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.38.0
+    hooks:
+      - id: markdownlint
+        args: ['--config', '.markdownlint.json']
+        files: '^documents/.*\.md$'
+        exclude: '^documents/.*\bindex\.md$'
+
+  # Frontmatter validation (local hook)
+  - repo: local
+    hooks:
+      - id: validate-frontmatter
+        name: Validate article frontmatter
+        entry: scripts/validate_frontmatter.py
+        language: python
+        additional_dependencies: ['pyyaml']
+        files: '^documents/core-embedded-cpp/.*\.md$'
+        exclude: '(index\.md|tags\.md)$'
+        pass_filenames: false
+
+      - id: clang-format
+        name: clang-format C/C++ sources
+        entry: clang-format -i
+        language: system
+        files: '\.(c|cc|cpp|cxx|h|hh|hpp|hxx)$'
+
+      - id: update-translation-coverage
+        name: Update translation coverage
+        entry: python3 scripts/coverage.py --update
+        language: system
+        always_run: true
+        pass_filenames: false
+
+  # Check for added large files
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-added-large-files
+        args: ['--maxkb=1500']
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        files: '^documents/.*\.md$'
+      - id: check-yaml
+        files: '^\.github/.*\.ya?ml$'

.pre-commit-config.yaml

@@ -6,18 +6,20 @@
 
 1. Fork 本仓库
 2. 创建你的特性分支 (`git switch -c feature/amazing-feature`)
-3. 安装本地 Git hook (`pnpm hooks:install` 或 `scripts/setup_precommit.sh`)
+3. 安装 pre-commit 提交前检查 (`pnpm hooks:install` 或 `scripts/setup_precommit.sh`)
 4. 提交更改 (`git commit -m '添加某功能'`)
 5. 推送到分支 (`git push origin feature/amazing-feature`)
 6. 创建 Pull Request
 
 ## 提交前自动化
 
-本仓库使用可追踪的原生 Git hook，配置位于 `.githooks/pre-commit`。安装后，每次 `git commit` 前会自动执行：
+本仓库使用 [pre-commit](https://pre-commit.com/) 管理提交前检查，配置位于 `.pre-commit-config.yaml`。安装后，每次 `git commit` 前会自动执行：
 
+- Markdown lint、frontmatter 校验、大文件和基础空白检查
 - 对已暂存的 C/C++ 源文件和头文件运行 `clang-format -i`
 - 运行 `python3 scripts/coverage.py --update` 检查英文翻译覆盖率并更新 `README.md`
-- 对 hook 自动修改的文件执行 `git add`，因此通常不需要因为格式化或覆盖率徽章变化再次手动提交
+
+如果 hook 修改了文件，pre-commit 会停止本次提交并提示重新暂存。请检查变更后重新执行 `git add` 和 `git commit`。
 
 首次克隆仓库后运行：
 
@@ -34,10 +36,13 @@ scripts/setup_precommit.sh
 
 hook 依赖本机已安装：
 
+- `pre-commit`：用于运行提交前检查，可通过 `pipx install pre-commit` 安装
 - `python3`：用于翻译覆盖率统计
 - `clang-format`：用于 C/C++ 代码格式化
 
-为了避免把未准备提交的内容一起带入 commit，如果已暂存的 C/C++ 文件或 `README.md` 同时还有未暂存改动，hook 会停止并提示先整理工作区。确实需要临时跳过 hook 时，可以使用 `git commit --no-verify`，但不建议在 PR 提交中长期绕过。
+pre-commit 会在运行检查前临时隔离未暂存改动，避免把未准备提交的内容混入本次提交。确实需要临时跳过 hook 时，可以使用 `git commit --no-verify`，但不建议在 PR 提交中长期绕过。
+
+日常验证请使用 `pre-commit run` 检查已暂存文件。`pre-commit run --all-files` 会对全仓文件运行自动修复型 hook，包括对所有 C/C++ 文件执行 `clang-format -i`。
 
 ## 文章规范
 

CONTRIBUTING.md

@@ -127,7 +127,7 @@ flowchart TD
 | `pnpm build` | Production build with per-volume parallel build and search-index merge |
 | `pnpm build:single` | Run the regular single VitePress build |
 | `pnpm preview` | Preview the production build |
-| `pnpm hooks:install` / `scripts/setup_precommit.sh` | Install the pre-commit Git hook |
+| `pnpm hooks:install` / `scripts/setup_precommit.sh` | Install pre-commit checks |
 | `pnpm coverage` | Show English translation coverage |
 | `pnpm coverage:update` | Update the English coverage badge in `README.md` |
 | `python3 scripts/validate_frontmatter.py` | Validate article frontmatter |

README.en.md

@@ -135,7 +135,7 @@ flowchart TD
 | `pnpm build:single` | 使用 VitePress 单体构建 |
 | `pnpm check:links` | 检查 Markdown 与组件内部链接有效性 |
 | `pnpm preview` | 预览生产构建结果 |
-| `pnpm hooks:install` / `scripts/setup_precommit.sh` | 安装提交前 Git hook |
+| `pnpm hooks:install` / `scripts/setup_precommit.sh` | 安装 pre-commit 提交前检查 |
 | `pnpm coverage` | 查看英文翻译覆盖率 |
 | `pnpm coverage:update` | 更新 `README.md` 中的英文翻译覆盖率徽章 |
 | `python3 scripts/validate_frontmatter.py` | 验证文章 frontmatter |

README.md

@@ -4,16 +4,14 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-HOOKS_DIR="$PROJECT_ROOT/.githooks"
-PRE_COMMIT_HOOK="$HOOKS_DIR/pre-commit"
 
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 NC='\033[0m'
 
 echo "=============================="
-echo " Git Hook Setup"
+echo " Pre-commit Hook Setup"
 echo "=============================="
 echo ""
 
@@ -22,15 +20,27 @@ if ! git -C "$PROJECT_ROOT" rev-parse --git-dir >/dev/null 2>&1; then
     exit 1
 fi
 
-if [ ! -f "$PRE_COMMIT_HOOK" ]; then
-    echo -e "${RED}ERROR: missing $PRE_COMMIT_HOOK${NC}"
+if ! command -v pre-commit >/dev/null 2>&1; then
+    echo -e "${RED}ERROR: pre-commit is required.${NC}"
+    echo ""
+    echo "Install it first, for example:"
+    echo "  pipx install pre-commit"
+    echo "  # or: python3 -m pip install --user pre-commit"
     exit 1
 fi
 
-chmod +x "$PRE_COMMIT_HOOK"
-git -C "$PROJECT_ROOT" config core.hooksPath .githooks
+cd "$PROJECT_ROOT"
+
+current_hooks_path="$(git -C "$PROJECT_ROOT" config --get core.hooksPath || true)"
+if [ -n "$current_hooks_path" ]; then
+    echo -e "${YELLOW}Removing core.hooksPath=$current_hooks_path so .git/hooks/pre-commit is used.${NC}"
+    git -C "$PROJECT_ROOT" config --unset core.hooksPath
+fi
 
-echo -e "${GREEN}Installed native Git hooks via core.hooksPath=.githooks${NC}"
+pre-commit install --config "$PROJECT_ROOT/.pre-commit-config.yaml"
+
+echo ""
+echo -e "${GREEN}Installed pre-commit hooks.${NC}"
 echo ""
 
 missing_tools=()
@@ -41,24 +51,24 @@ for tool in python3 clang-format; do
 done
 
 if [ "${#missing_tools[@]}" -gt 0 ]; then
-    echo -e "${YELLOW}Missing optional/required hook tools:${NC}"
+    echo -e "${YELLOW}Missing hook tools:${NC}"
     printf '  - %s\n' "${missing_tools[@]}"
     echo ""
     echo "Install them before committing files that need the corresponding checks."
 else
-    echo -e "${GREEN}Required hook tools detected:${NC}"
+    echo -e "${GREEN}Hook tools detected:${NC}"
     echo "  - python3: $(python3 --version 2>&1)"
     echo "  - clang-format: $(clang-format --version 2>&1)"
 fi
 
 echo ""
 echo "What runs before each commit:"
+echo "  - markdownlint/frontmatter/basic file checks from .pre-commit-config.yaml"
 echo "  - clang-format on staged C/C++ source and header files"
 echo "  - python3 scripts/coverage.py --update"
-echo "  - git add for files updated by the hook, so one git commit is enough"
 echo ""
 echo "Run manually:"
-echo "  .githooks/pre-commit"
+echo "  pre-commit run --all-files"
 echo ""
 echo "Bypass only when necessary:"
 echo "  git commit --no-verify -m 'message'"