npm package: @huaiyou/hooks-git
Description: Git hooks configuration with Husky, Commitlint and Lint-staged
Latest version: 2.3.0

# @huaiyou/hooks-git

> Git 钩子配置，包含 Husky、Commitlint 和 Lint-staged，确保代码质量和提交规范。

## 📦 安装

```bash
pnpm add -D @huaiyou/hooks-git
```

> 注意：该包会自动处理所有依赖关系，无需手动安装 husky、@commitlint/cli 和 lint-staged。

## 🚀 快速开始

### 一键初始化（推荐）

使用以下命令一键完成所有配置：

```bash
npx hy-hooks-git init
```

该命令将自动：

- 检查并初始化 Git 仓库（如果尚未初始化）
- 安装并配置 Husky
- 添加 commit-msg 和 pre-commit 钩子
- 创建 commitlint.config.js 和 lint-staged.config.js 配置文件
- 更新 package.json 脚本

### 交互式初始化

如需自定义配置，可以使用交互式模式：

```bash
npx hy-hooks-git init --interactive
```

### 手动配置（不推荐）

如果需要手动配置，可以按照以下步骤进行：

#### 1. 安装 Husky

在项目根目录运行：

```bash
pnpm prepare
```

#### 2. 复制配置文件

将以下文件复制到项目根目录：

**commitlint.config.js**:

```javascript
module.exports = require('@huaiyou/hooks-git/commitlint');
```

**lint-staged.config.js**:

```javascript
const { createLintStagedConfig } = require('@huaiyou/hooks-git/lint-staged');
module.exports = createLintStagedConfig();
```

#### 3. 配置 Husky 钩子

**创建 .husky/pre-commit**:

```bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

pnpm lint-staged
```

**创建 .husky/commit-msg**:

```bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

pnpm commitlint --edit $1
```

#### 4. 添加脚本

在 `package.json` 中：

```json
{
  "scripts": {
    "prepare": "husky install"
  }
}
```

### 回滚初始化

如果需要回滚所有配置，可以使用以下命令：

```bash
npx hy-hooks-git rollback
```

该命令将自动：

- 删除 .husky 目录及其包含的钩子
- 删除配置文件（commitlint.config.js 和 lint-staged.config.js）
- 从 package.json 中移除 prepare 脚本

## ✨ 特性

### Commitlint

强制执行 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

- ✅ **feat**: 新功能
- ✅ **fix**: Bug 修复
- ✅ **docs**: 文档更新
- ✅ **style**: 代码格式（不影响代码运行）
- ✅ **refactor**: 重构
- ✅ **perf**: 性能优化
- ✅ **test**: 测试相关
- ✅ **build**: 构建系统或依赖
- ✅ **ci**: CI 配置
- ✅ **chore**: 其他修改
- ✅ **revert**: 回退提交

### Lint-staged

在提交前自动运行代码检查和格式化：

- **TypeScript/JavaScript**: ESLint + Prettier
- **JSON/Markdown/YAML**: Prettier

## 📝 提交消息格式

### 基本格式

```
<type>(<scope>): <subject>

<body>

<footer>
```

### 示例

```bash
# 简单提交
feat: add user authentication

# 带作用域
feat(auth): implement JWT token validation

# 带详细描述
fix(api): resolve CORS issue in production

This fix addresses the CORS error that was preventing
requests from the frontend in production environment.

Closes #123
```

### 规则

1. **type**: 必填，见上述类型列表
2. **scope**: 可选，表示影响范围
3. **subject**: 必填，简短描述（小写开头，不要句号）
4. **body**: 可选，详细描述
5. **footer**: 可选，关联 Issue 或 Breaking Changes

## 🔧 自定义配置

### 修改 Commitlint 规则

创建 `commitlint.config.js`:

```javascript
const baseConfig = require('@huaiyou/hooks-git/commitlint');

module.exports = {
  ...baseConfig,
  rules: {
    ...baseConfig.rules,
    'subject-max-length': [2, 'always', 100], // 自定义主题长度
  },
};
```

### 修改 Lint-staged 规则

创建 `lint-staged.config.js`:

```javascript
const { createLintStagedConfig } = require('@huaiyou/hooks-git/lint-staged');

// 获取基础配置
const baseConfig = createLintStagedConfig();

module.exports = {
  ...baseConfig,
  '*.{ts,tsx}': [
    'eslint --fix',
    'prettier --write',
    'vitest related --run', // 添加测试
  ],
};
```

或者直接扩展配置函数：

```javascript
const { createLintStagedConfig } = require('@huaiyou/hooks-git/lint-staged');

module.exports = {
  ...createLintStagedConfig(),
  '*.{ts,tsx}': [
    'eslint --fix',
    'prettier --write',
    'vitest related --run', // 添加测试
  ],
};
```

## 🚫 跳过钩子

### 临时跳过（不推荐）

```bash
# 跳过 pre-commit 钩子
git commit --no-verify

# 跳过 commit-msg 钩子
git commit -m "message" --no-verify
```

### 禁用钩子

```bash
# 临时禁用 Husky
export HUSKY=0

# 提交
git commit -m "message"

# 重新启用
unset HUSKY
```

## 📋 最佳实践

1. **原子提交**: 每次提交只做一件事
2. **清晰描述**: 提交信息要能让他人理解
3. **关联 Issue**: 使用 `Closes #123` 关联问题
4. **Breaking Changes**: 重大变更要在 footer 说明
5. **定期提交**: 不要积累太多修改

### Breaking Changes 示例

```bash
feat(api): change authentication method

BREAKING CHANGE: The old API key authentication is replaced
with JWT tokens. All clients must update to use the new
authentication method.
```

## 🔍 故障排除

### Husky 钩子不执行

```bash
# 重新安装 Husky
rm -rf .husky
pnpm prepare
```

### Commitlint 不工作

```bash
# 检查配置文件
cat commitlint.config.js

# 手动测试
echo "test: message" | pnpm commitlint
```

### Lint-staged 不运行

```bash
# 检查配置
cat lint-staged.config.js

# 手动运行
pnpm lint-staged
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 License

MIT