@huaiyou/hooks-git

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

📦 安装

pnpm add -D @huaiyou/hooks-git

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

🚀 快速开始

一键初始化（推荐）

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

npx hy-hooks-git init

该命令将自动：

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

交互式初始化

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

npx hy-hooks-git init --interactive

手动配置（不推荐）

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

1. 安装 Husky

在项目根目录运行：

pnpm prepare

2. 复制配置文件

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

commitlint.config.js:

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

lint-staged.config.js:

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

3. 配置 Husky 钩子

创建 .husky/pre-commit:

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

pnpm lint-staged

创建 .husky/commit-msg:

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

pnpm commitlint --edit $1

4. 添加脚本

在 package.json 中：

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

回滚初始化

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

npx hy-hooks-git rollback

该命令将自动：

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

✨ 特性

Commitlint

强制执行 Conventional Commits 规范：

• ✅ 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>

示例

# 简单提交
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:

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:

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

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

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

或者直接扩展配置函数：

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

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

🚫 跳过钩子

临时跳过（不推荐）

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

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

禁用钩子

# 临时禁用 Husky
export HUSKY=0

# 提交
git commit -m "message"

# 重新启用
unset HUSKY

📋 最佳实践

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

Breaking Changes 示例

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 钩子不执行

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

Commitlint 不工作

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

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

Lint-staged 不运行

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

# 手动运行
pnpm lint-staged

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT