# git-hook

**Repository Path**: LOVEDDZ/git-hook

## Basic Information

- **Project Name**: git-hook
- **Description**: Git Hook - 代码规范检查工具
基于阿里代码规范的 Git pre-commit 钩子工具。在提交代码时自动检查规范，不符合规范的代码将被阻断，并给出明确的错误提示和修复建议。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Git Hook - 代码规范检查工具

基于阿里代码规范的 Git pre-commit 钩子工具。在提交代码时自动检查规范，不符合规范的代码将被阻断，并给出明确的错误提示和修复建议。

## 目录

- [功能特性](#功能特性)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [配置到项目](#配置到项目)
- [检查规则](#检查规则)
- [常见问题](#常见问题)
- [高级配置](#高级配置)

## 功能特性

| 特性 | 说明 |
|-----|------|
| 自动检查 | `git commit` 时自动触发，无需手动操作 |
| 规范阻断 | 不符合规范的代码无法提交 |
| 清晰提示 | 显示文件、行号、规则名、修复建议 |
| 多语言支持 | Java（已完成）、Python、JS/TS（规划中） |

## 环境要求

| 依赖 | 版本 | 说明 |
|-----|------|------|
| Python | 3.11+ | 运行脚本 |
| Git | 任意版本 | 版本控制 |
| Java | 8+ | Java 代码检查（可选） |

## 快速开始

### 1. 安装 pre-commit

```bash
pip install pre-commit
```

### 2. 配置到项目

**方式一：使用配置脚本（推荐）**

```bash
# 在 git-hook 目录运行
python setup.py /path/to/your/project

# Windows 示例
python setup.py D:\projects\my-app
```

执行后会自动：
1. 复制配置文件到目标项目
2. **预加载依赖（PMD + P3C）** - 首次提交无需等待下载
3. 安装 pre-commit 钩子

**方式二：手动配置**

```bash
# 1. 复制以下文件到你的项目根目录
#    - .pre-commit-config.yaml
#    - scripts/
#    - config/

# 2. 进入项目目录
cd /path/to/your/project

# 3. 安装钩子
pre-commit install
```

### 3. 验证安装

```bash
# 手动触发检查
pre-commit run --all-files

# 预期输出
Java 代码规范检查通过
```

## 配置到项目

### 文件结构

配置完成后，你的项目结构如下：

```
your-project/
├── .git/
├── .pre-commit-config.yaml    # pre-commit 配置
├── scripts/
│   └── run-java-check.py      # Java 检查脚本
├── config/
│   └── rules/
│       └── java-rules.xml     # 规则配置
└── src/                       # 你的源代码
```

### 提交流程

```
git add .
    ↓
git commit -m "your message"
    ↓
pre-commit 自动运行
    ↓
┌─────────────────────────────────┐
│  检查暂存的 .java 文件           │
│                                 │
│  ├─ 无违规 → 提交成功 ✓          │
│  └─ 有违规 → 提交被阻断 ✗        │
│              显示错误详情         │
└─────────────────────────────────┘
```

## 检查规则

### Java 规范（Alibaba P3C）

| 规则类别 | 优先级 | 说明 | 示例 |
|---------|--------|------|------|
| 并发处理 | Blocker | 线程安全问题 | 线程池必须命名 |
| 命名规范 | Critical | 命名不符合规范 | 类名使用 UpperCamelCase |
| 集合处理 | Critical | 集合操作问题 | ArrayList 初始化指定容量 |
| 异常处理 | Critical | 异常处理问题 | 禁止捕获异常后不做处理 |
| 常量定义 | Critical | 常量定义问题 | 魔法值直接使用 |
| ORM 规范 | Critical | 数据库操作问题 | 禁止 SELECT * |
| 流程控制 | Major | 控制流问题 | switch 必须有 default |
| 面向对象 | Major | OOP 问题 | 避免通过对象引用访问静态变量 |
| 注释规范 | Minor | 注释问题 | 方法缺少 Javadoc |

### 规则优先级

| 优先级 | 标识 | 说明 | 行为 |
|-------|------|------|------|
| 1 | Blocker | 必须修复 | 阻断提交 |
| 2 | Critical | 严重问题 | 阻断提交 |
| 3 | Major | 重要问题 | 阻断提交 |
| 4 | Minor | 次要问题 | 阻断提交 |
| 5 | Info | 建议 | 显示警告 |

## 使用示例

### 正常提交流程

```bash
$ git add src/Main.java
$ git commit -m "feat: add main class"

[INFO] 检查 1 个 Java 文件...
[OK] Java 代码规范检查通过
[main abc1234] feat: add main class
 1 file changed, 10 insertions(+)
```

### 违规被阻断

```bash
$ git add src/UserManager.java
$ git commit -m "feat: add user manager"

[INFO] 检查 1 个 Java 文件...

[ERROR] Java 代码规范检查失败
发现 2 个违规项：

[FILE] /project/src/UserManager.java
  Line 15 [CRITICAL]
    [X] ClassNamingShouldBeCamelRule
      类名【usermanager】不符合 UpperCamelCase 风格
  Line 28 [BLOCKER]
    [X] ThreadShouldSetNameRule
      线程池必须手动命名，便于排查问题

[TIPS]
  - 请修复以上违规项后重新提交
  - 如需临时跳过检查：git commit --no-verify
```

### 临时跳过检查

```bash
# 不推荐，仅在紧急情况使用
git commit --no-verify -m "emergency fix"
```

## 常见问题

### Q: 首次提交需要等待下载吗？

A: **不需要**。使用 `setup.py` 配置项目时，会自动从 `git-hook-cache.zip` 解压依赖到本地缓存，首次提交即可直接运行检查。

缓存位置：
- Windows: `%LOCALAPPDATA%\git-hook-cache\`
- Linux/macOS: `~/.cache/git-hook/`

如果没有 `git-hook-cache.zip`，首次提交时会自动从网络下载（约 50MB）。

### Q: 如何忽略某个规则？

A: 在代码中添加注解：

```java
@SuppressWarnings("PMD.ClassNamingShouldBeCamelRule") // NOSONAR
public class myClass {
    // ...
}
```

### Q: 如何排除某些文件？

A: 在 `.pre-commit-config.yaml` 中添加排除规则：

```yaml
repos:
  - repo: local
    hooks:
      - id: alibaba-p3c-java
        # ... 其他配置
        exclude: ^generated/  # 排除 generated 目录
```

### Q: Java 未安装怎么办？

A: 如果未安装 Java，检查会自动跳过，不会阻断提交。建议安装 Java 8+ 以启用检查功能。

### Q: 如何只检查新增文件？

A: pre-commit 默认只检查暂存文件。如需检查所有文件：

```bash
pre-commit run --all-files
```

### Q: 如何卸载？

A: 在项目目录运行：

```bash
pre-commit uninstall
rm -rf scripts/ config/ .pre-commit-config.yaml
```

## 高级配置

### 自定义规则优先级

编辑 `config/rules/java-rules.xml`：

```xml
<!-- 调整并发规则为最高优先级 -->
<rule ref="rulesets/java/ali-concurrent.xml">
    <priority>1</priority>
</rule>

<!-- 注释规则降级为提示 -->
<rule ref="rulesets/java/ali-comment.xml">
    <priority>5</priority>
</rule>
```

### 排除特定规则

```xml
<!-- 排除某个规则 -->
<rule ref="rulesets/java/ali-naming.xml">
    <exclude name="ClassNamingShouldBeCamelRule"/>
</rule>
```

### 配置 SHA256 校验（增强安全性）

编辑 `scripts/run-java-check.py`，配置真实的哈希值：

```python
PMD_SHA256 = "实际的 SHA256 值"
P3C_SHA256 = "实际的 SHA256 值"
```

获取哈希值：

```bash
# PMD
curl -L <PMD_URL> | sha256sum

# P3C
curl -L <P3C_JAR_URL> | sha256sum
```

### CI/CD 集成

在 CI 流程中添加：

```yaml
# GitHub Actions
- name: Install pre-commit
  run: pip install pre-commit

- name: Run checks
  run: pre-commit run --all-files
```

```yaml
# GitLab CI
lint:
  script:
    - pip install pre-commit
    - pre-commit run --all-files
```

## 支持的语言

| 语言 | 状态 | 工具 |
|------|------|------|
| Java | 已完成 | PMD + Alibaba P3C |
| Python | 规划中 | ruff / pylint |
| JavaScript | 规划中 | ESLint |
| TypeScript | 规划中 | ESLint |

## 命令速查

| 命令 | 说明 |
|-----|------|
| `pre-commit install` | 安装钩子 |
| `pre-commit uninstall` | 卸载钩子 |
| `pre-commit run --all-files` | 检查所有文件 |
| `pre-commit run alibaba-p3c-java` | 只检查 Java |
| `git commit --no-verify` | 跳过检查 |
| `python setup.py <项目路径>` | 一键配置到项目 |

## 参考资料

- [阿里巴巴 Java 开发手册](https://github.com/alibaba/p3c)
- [PMD 静态代码分析](https://pmd.github.io/)
- [pre-commit 框架](https://pre-commit.com/)

## License

MIT License