OpenClaw02_GitHook使用

在阅读OpenClaw的源码时，可以看到openClaw在设计的时候，频繁的时候各种hook，当前针对代码提交之前的git hook进行知识拆解

文章目录

OpenClaw02_GitHook使用
1-GitHook介绍
- [1-git init文件夹](#1-git init文件夹)
- 2-hooks文件夹
- - [一、本地提交相关 Hook](#一、本地提交相关 Hook)
  - [二、代码重写相关 Hook](#二、代码重写相关 Hook)
  - [三、远程交互相关 Hook](#三、远程交互相关 Hook)
  - [四、其他实用 Hook](#四、其他实用 Hook)
  - 五、常用组合方案示例
  - 1-前端项目典型配置
  - 2-Python项目典型配置
- 六、现代管理工具
- 七、关键建议
[2-Git Hooks 完全指南](#2-Git Hooks 完全指南)
- 一、基础概念
- - [1.1 什么是 Git Hooks](#1.1 什么是 Git Hooks)
  - [1.2 核心机制](#1.2 核心机制)
- [二、客户端钩子（Client-Side Hooks）](#二、客户端钩子（Client-Side Hooks）)
- - [2.1 提交工作流钩子](#2.1 提交工作流钩子)
  - [2.2 补丁/邮件工作流钩子](#2.2 补丁/邮件工作流钩子)
  - [2.3 其他客户端钩子](#2.3 其他客户端钩子)
- [三、服务端钩子（Server-Side Hooks）](#三、服务端钩子（Server-Side Hooks）)
- 四、工具与实践
- - [4.1 常用管理工具](#4.1 常用管理工具)
  - [4.2 Husky 快速上手](#4.2 Husky 快速上手)
  - [4.3 pre-commit 框架配置](#4.3 pre-commit 框架配置)
  - [4.4 团队共享 Hooks 方案](#4.4 团队共享 Hooks 方案)
- 五、最佳实践
- - [5.1 性能原则](#5.1 性能原则)
  - [5.2 绕过与调试](#5.2 绕过与调试)
  - [5.3 安全注意事项](#5.3 安全注意事项)
- 六、钩子速查表
- 参考资源

1-GitHook介绍

1-git init文件夹

bash 复制代码

tree
.
├── config
├── description
├── HEAD
├── hooks
│   ├── applypatch-msg.sample
│   ├── commit-msg.sample
│   ├── fsmonitor-watchman.sample
│   ├── post-update.sample
│   ├── pre-applypatch.sample
│   ├── pre-commit.sample
│   ├── pre-merge-commit.sample
│   ├── pre-push.sample
│   ├── pre-rebase.sample
│   ├── pre-receive.sample
│   ├── prepare-commit-msg.sample
│   ├── push-to-checkout.sample
│   ├── sendemail-validate.sample
│   └── update.sample
├── info
│   └── exclude
├── objects
│   ├── info
│   └── pack
└── refs
    ├── heads
    └── tags

2-hooks文件夹

我来为你整理Git提交时常用的Hook版本及其用途。这些Hook按执行顺序排列，覆盖了从提交准备到推送完成的完整工作流。

一、本地提交相关 Hook

Hook 名称	触发时机	常用版本/用途
`pre-commit`	执行 `git commit` 前	最常用，用于代码格式化（Prettier/Black）、Lint检查（ESLint/Flake8）、单元测试、敏感信息扫描
`prepare-commit-msg`	打开提交编辑器前	自动生成提交信息模板、插入Jira/Trello任务ID、添加提交前缀（如`[WIP]`）
`commit-msg`	提交信息编辑完成后	常用，验证提交信息格式（Conventional Commits）、检查字数限制、禁止特定关键词
`post-commit`	提交完成后	发送通知（Slack/钉钉）、记录提交统计、触发本地CI预览

二、代码重写相关 Hook

Hook 名称	触发时机	常用版本/用途
`pre-rebase`	执行 `git rebase` 前	检查是否允许变基、防止对公共分支变基、备份当前状态
`post-checkout`	`git checkout` 或 `git clone` 后	切换分支时自动安装依赖、更新子模块、清理/重建构建产物
`post-merge`	`git merge` 完成后	自动安装新依赖（package.json变化时）、执行数据库迁移、发送合并通知
`post-rewrite`	命令重写提交后（如`git commit --amend`）	同步更新关联任务状态、重新签名提交

三、远程交互相关 Hook

Hook 名称	触发时机	常用版本/用途
`pre-push`	执行 `git push` 前	非常常用，运行完整测试套件、检查分支命名规范、验证远程分支状态、防止强制推送主分支
`pre-receive`	服务端接收推送前	服务端强制检查：代码规范、测试覆盖率、权限验证、提交签名验证
`update`	服务端更新每个引用前	细粒度权限控制（按分支/标签）、更复杂的推送策略验证
`post-receive`	服务端接收推送后	触发CI/CD流水线（GitLab CI/GitHub Actions）、部署到生产环境、发送团队通知

四、其他实用 Hook

Hook 名称	触发时机	常用版本/用途
`pre-applypatch`	应用 `git apply` 或 `git am` 前	验证补丁格式、检查补丁来源安全性
`post-applypatch`	补丁应用完成后	自动构建测试、发送补丁应用通知
`pre-auto-gc`	`git gc --auto` 执行前	检查磁盘空间、决定是否允许自动垃圾回收

五、常用组合方案示例

1-前端项目典型配置

bash 复制代码

# .git/hooks/pre-commit
#!/bin/sh
npx lint-staged        # 对暂存文件运行ESLint + Prettier
npm run test:staged    # 运行相关单元测试

bash 复制代码

# .git/hooks/commit-msg
#!/bin/sh
npx commitlint --edit $1  # 验证Conventional Commits格式

bash 复制代码

# .git/hooks/pre-push
#!/bin/sh
npm run test:ci        # 完整测试套件
npm run build          # 验证构建是否成功
npm run type-check     # TypeScript类型检查

2-Python项目典型配置

bash 复制代码

# .git/hooks/pre-commit
#!/bin/sh
black --check .        # 代码格式化检查
flake8 .               # 风格检查
pytest -x -q           # 快速测试

六、现代管理工具

工具	用途	特点
Husky (Node.js)	统一管理Git Hooks	最流行的方案，支持共享配置、自动安装
pre-commit (Python)	多语言Hook框架	跨语言支持，丰富的现成规则库
Lefthook (Go)	快速Hook管理器	并行执行，配置简单，跨平台
git-hooks	轻量级管理	Bash实现，零依赖

七、关键建议

pre-commit 和 pre-push 是最值得投入的两个Hook，能拦截80%的问题代码
服务端Hook（pre-receive/update）是最后一道防线，即使本地Hook被绕过也能生效
使用 Husky 或 pre-commit 框架避免手动维护 .git/hooks 目录（该目录不纳入版本控制）
Hook执行失败会阻止对应Git操作，因此要保持检查脚本快速（pre-commit建议<5秒）

我将帮你阅读并整理 githooks 的官方文档，为你生成一份结构清晰、内容精炼的知识博客。

让我通过搜索来获取 githooks 的相关信息：

基于搜索结果，我为你整理了一份完整的 Git Hooks 知识博客。由于无法直接访问官方文档，以下内容综合了多个权威来源的信息：

2-Git Hooks 完全指南

Git Hooks 是 Git 在特定事件触发时自动执行的脚本，用于自动化工作流、代码质量检查和流程管控。

一、基础概念

1.1 什么是 Git Hooks

Git Hooks 是存储在 .git/hooks 目录下的可执行脚本，当 Git 执行特定操作（如提交、推送、合并等）时自动触发。它们允许开发者在关键节点插入自定义逻辑，实现：

代码质量门禁：在提交前运行 lint、测试
流程自动化：自动生成文档、发送通知
安全管控：防止敏感信息泄露、限制分支操作

1.2 核心机制

位置：.git/hooks/（本地仓库，不纳入版本控制）
命名：与钩子名称完全一致（无扩展名或 .sample 后缀）
权限：必须设置为可执行（chmod +x）
控制流：返回非零退出码会中止当前 Git 操作

二、客户端钩子（Client-Side Hooks）

2.1 提交工作流钩子

钩子名称	触发时机	可中止操作	典型用途
`pre-commit`	`git commit` 前，输入提交信息前	✅	代码格式化检查、lint、单元测试
`prepare-commit-msg`	打开提交信息编辑器前	✅	自动插入提交模板、关联 Issue 编号
`commit-msg`	提交信息编辑完成后	✅	验证提交信息格式（Conventional Commits）
`post-commit`	提交完成后	❌	发送通知、触发 CI、更新日志

pre-commit 示例：

bash 复制代码

#!/bin/sh
# .git/hooks/pre-commit
echo "Running pre-commit checks..."

# 运行 linter
npm run lint
if [ $? -ne 0 ]; then
    echo "❌ Lint failed. Commit aborted."
    exit 1
fi

exit 0

commit-msg 示例（验证 Conventional Commits）：

bash 复制代码

#!/bin/sh
COMMIT_MSG=$(cat "$1")
PATTERN="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: .{1,}"

if ! echo "$COMMIT_MSG" | grep -qE "$PATTERN"; then
    echo "ERROR: Commit message must follow Conventional Commits format."
    echo "Example: feat(auth): add OAuth2 login support"
    exit 1
fi

2.2 补丁/邮件工作流钩子

钩子名称	触发时机	说明
`applypatch-msg`	`git am` 执行前	验证补丁提交信息
`pre-applypatch`	应用补丁后，提交前	运行测试检查补丁
`post-applypatch`	补丁提交完成后	通知维护者

2.3 其他客户端钩子

钩子名称	触发时机	可中止	典型用途
`pre-rebase`	变基操作前	✅	防止对已推送提交进行变基
`post-checkout`	`git checkout` 后	❌	清理文件、设置环境、显示切换信息
`post-merge`	合并完成后	❌	清理合并冲突标记、恢复依赖
`pre-push`	`git push` 前	✅	运行完整测试套件、检查分支命名规范
`pre-auto-gc`	`git gc --auto` 前	✅	自定义垃圾回收逻辑

pre-push 示例：

bash 复制代码

#!/bin/sh
# 阻止直接向 main 分支推送
BRANCH=$(git symbolic-ref --short HEAD)
if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
    echo "ERROR: Direct push to $BRANCH is not allowed. Use PR instead."
    exit 1
fi

# 运行测试套件
npm test || exit 1

三、服务端钩子（Server-Side Hooks）

用于自托管 Git 服务器（如 Gitea、GitLab Self-Hosted），在接收推送时执行策略检查。

钩子名称	触发时机	参数	典型用途
`pre-receive`	推送到达时，更新引用前	stdin 接收 `<oldrev> <newrev> <refname>`	全局推送策略：文件大小限制、禁止强制推送、验证签名
`update`	每个引用更新前	`<refname> <oldrev> <newrev>`	分支级策略：保护特定分支
`post-receive`	推送完成后	stdin 接收 `<oldrev> <newrev> <refname>`	触发部署、发送通知、更新工单系统
`post-update`	所有引用更新后	更新的引用列表	更新服务器信息（已较少使用）

pre-receive 示例（限制文件大小）：

bash 复制代码

#!/bin/sh
# 拒绝包含超过 10MB 文件的提交
while read oldrev newrev refname; do
    COMMITS=$(git rev-list "$oldrev..$newrev" 2>/dev/null || echo "$newrev")
    for commit in $COMMITS; do
        git diff-tree -r --diff-filter=d "$commit" | while read a b c d e f; do
            size=$(git cat-file -s "$d")
            if [ "$size" -gt 10485760 ]; then
                echo "ERROR: File $f exceeds 10MB limit"
                exit 1
            fi
        done
    done
done

四、工具与实践

4.1 常用管理工具

工具	用途	特点
Husky	Node.js 项目钩子管理	自动安装、版本控制友好、配置简单
pre-commit	多语言钩子框架	Python 编写、丰富的现成 hooks、支持本地脚本
lint-staged	仅对暂存文件运行检查	与 Husky 配合，提升效率

4.2 Husky 快速上手

bash 复制代码

# 安装
npm install --save-dev husky

# 初始化（创建 .husky/ 目录）
npx husky init

# 创建钩子
echo "npm run lint" > .husky/pre-commit
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

4.3 pre-commit 框架配置

.pre-commit-config.yaml 示例：

yaml 复制代码

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
  
  - repo: local
    hooks:
      - id: custom-test
        name: Run custom tests
        entry: ./scripts/test.sh
        language: script
        stages: [pre-push]

4.4 团队共享 Hooks 方案

由于 .git/hooks 不纳入版本控制，推荐以下共享方式：

Husky/pre-commit ：将配置存入仓库，通过 npm install 自动安装

符号链接方案 ：

bash 复制代码

# 将 hooks 存入版本控制（如 .githooks/）
git config core.hooksPath .githooks

安装脚本 ：

bash 复制代码

# install-hooks.sh
cp .githooks/* .git/hooks/
chmod +x .git/hooks/*

五、最佳实践

5.1 性能原则

pre-commit 保持快速（< 5 秒），仅运行增量检查
pre-push 运行完整测试套件
避免在 hooks 中执行网络请求或长时间任务

5.2 绕过与调试

bash 复制代码

# 临时绕过钩子（紧急情况）
git commit --no-verify
git push --no-verify

# 手动运行特定钩子
pre-commit run --all-files

5.3 安全注意事项

服务端钩子是关键安全防线，客户端钩子可被绕过
敏感操作（如部署密钥检查）必须在服务端完成
避免在 hooks 中硬编码敏感信息

六、钩子速查表

复制代码

客户端钩子：
├── 提交流程
│   ├── pre-commit        # 提交前检查
│   ├── prepare-commit-msg # 准备提交信息模板
│   ├── commit-msg        # 验证提交信息
│   └── post-commit       # 提交后通知
├── 补丁流程
│   ├── applypatch-msg    # 验证补丁信息
│   ├── pre-applypatch    # 应用补丁前检查
│   └── post-applypatch   # 补丁提交后
├── 其他操作
│   ├── pre-rebase        # 变基前
│   ├── post-checkout     # 切换分支后
│   ├── post-merge        # 合并后
│   ├── pre-push          # 推送前（关键检查点）
│   └── pre-auto-gc       # 自动垃圾回收前

服务端钩子：
├── pre-receive           # 接收推送前（全局策略）
├── update                # 更新引用前（分支策略）
├── post-receive          # 推送完成后（部署触发）
└── post-update           # 所有引用更新后

参考资源

这份指南涵盖了 Git Hooks 的核心概念、所有主要钩子类型、实际代码示例以及现代工具链的最佳实践。建议根据项目需求从 pre-commit 和 commit-msg 开始实践，逐步扩展到 pre-push 和服务端钩子。