git-hygiene-enforcer

Git 规范执行器

在团队中贯彻一致且高质量的 Git 实践。

核心工作流

1. 选择规范：选择提交格式（Conventional Commits、Angular 等）
2. 设置提交钩子：通过 Git 钩子安装 commitlint
3. 配置分支规则：定义命名模式和保护规则
4. 创建 PR 模板：统一拉取请求说明
5. 添加工作流：使用 GitHub Actions 或 GitLab CI 执行自动化检查
6. 记录流程：编写包含 Git 指南的 CONTRIBUTING.md
7. 提供绕过方式：记录紧急覆盖流程

Conventional Commits

格式：<type>(<scope>): <description>

类型：

• feat：新功能
• fix：修复错误
• docs：文档变更
• style：代码风格变更（格式调整等）
• refactor：代码重构
• test：新增或修改测试
• chore：构建／工具变更
• perf：性能改进
• ci：CI/CD 变更

示例：

feat(auth): add OAuth2 login
fix(api): resolve race condition in user endpoint
docs(readme): update installation instructions
refactor(utils): simplify date formatting logic

提交钩子设置

使用 Husky + Commitlint

1. 安装依赖项：

npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
npx husky init

2. 配置 commitlint（commitlint.config.js）：

module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [
      2,
      "always",
      [
        "feat",
        "fix",
        "docs",
        "style",
        "refactor",
        "test",
        "chore",
        "perf",
        "ci",
      ],
    ],
    "subject-case": [2, "never", ["upper-case"]],
    "subject-empty": [2, "never"],
    "subject-full-stop": [2, "never", "."],
    "header-max-length": [2, "always", 100],
  },
};

3. 添加 commit-msg 钩子（.husky/commit-msg）：

#!/bin/sh
npx --no -- commitlint --edit $1

使用 pre-commit（Python）

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.0.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]

分支命名规范

模式： <type>/<ticket-id>-<description>

示例：

feature/AUTH-123-oauth-login
bugfix/API-456-user-race-condition
hotfix/PROD-789-payment-error
refactor/DB-321-optimize-queries

分支保护规则：

• 要求 PR 评审（1-2 位评审者）
• 要求状态检查通过
• 要求分支保持最新
• 强制使用线性历史记录（不允许合并提交）
• 要求提交经过签名（可选）

拉取请求模板

.github/pull_request_template.md

## Description



## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Related Issue

Closes #

## How Has This Been Tested?



- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual testing

## Checklist

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published

## Screenshots (if applicable)

替代方案：简单模板

## What



## Why



## How



## Testing

GitHub Actions 工作流

.github/workflows/pr-checks.yml

name: PR Checks

on:
  pull_request:
    branches: [main, develop]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Validate PR title
        uses: amannn/action-semantic-pull-request@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Check branch naming
        run: |
          BRANCH="${{ github.head_ref }}"
          if [[ ! $BRANCH =~ ^(feature|bugfix|hotfix|refactor|docs|chore)/.+ ]]; then
            echo "Branch name doesn't follow convention: <type>/<description>"
            exit 1
          fi

      - name: Lint commits
        uses: wagoid/commitlint-github-action@v5

      - name: Check for merge commits
        run: |
          if git log --merges origin/${{ github.base_ref }}..HEAD | grep -q 'Merge'; then
            echo "Merge commits detected. Please rebase your branch."
            exit 1
          fi

Git 配置

.gitattributes

# Auto detect text files and perform LF normalization
* text=auto

# Explicitly mark files as text
*.js text
*.ts text
*.json text
*.md text
*.yml text

# Binary files
*.png binary
*.jpg binary
*.gif binary
*.ico binary
*.woff binary
*.woff2 binary

.gitignore 最佳实践

# Dependencies
node_modules/
vendor/

# Environment
.env
.env.local

# Build outputs
dist/
build/
*.log

# IDE
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db

代码评审指南

CONTRIBUTING.md 章节

## Pull Request Process

1. **Create a branch** following naming convention: `type/description`
2. **Make commits** using conventional commit format
3. **Write tests** for new features or bug fixes
4. **Update documentation** if APIs change
5. **Ensure CI passes** before requesting review
6. **Request review** from 1-2 team members
7. **Address feedback** and update PR
8. **Squash and merge** when approved

## Code Review Checklist

**Reviewers should verify:**

- [ ] Code is clear and understandable
- [ ] Tests cover new/changed code
- [ ] No obvious bugs or security issues
- [ ] Follows project conventions
- [ ] Documentation is updated
- [ ] No unnecessary changes included

**Constructive feedback:**

- Be specific and actionable
- Assume good intent
- Ask questions instead of making demands
- Praise good solutions

提交消息验证

commit-msg 钩子示例

#!/bin/bash
# .husky/commit-msg

commit_msg=$(cat "$1")

# Check conventional commit format
if ! echo "$commit_msg" | grep -qE '^(feat|fix|docs|style|refactor|test|chore|perf|ci)(\(.+\))?: .+'; then
  echo "Error: Commit message doesn't follow Conventional Commits format"
  echo "Format: <type>(<scope>): <description>"
  echo "Example: feat(auth): add OAuth2 login"
  exit 1
fi

# Check message length
if [ ${#commit_msg} -gt 100 ]; then
  echo "Error: Commit message too long (max 100 characters)"
  exit 1
fi

紧急绕过说明

跳过钩子（谨慎使用）

# Skip commit message validation
git commit --no-verify -m "hotfix: critical production fix"

# Force push (use with caution)
git push --force-with-lease

# Override PR checks (requires admin)
# Use GitHub UI: "Merge without waiting for checks"

允许绕过的情况

• 生产环境热修复：影响用户的严重错误
• 回滚：撤销有问题的变更
• 紧急情况：基础设施中断

绕过操作文档

在 CONTRIBUTING.md 中记录：

## Emergency Procedures

In rare cases, you may need to bypass git hooks:

1. **Commit without hooks**: `git commit --no-verify`

   - Only for production hotfixes
   - Fix commit message in follow-up PR

2. **Force push**: `git push --force-with-lease`
   - After approved history rewrite
   - Coordinate with team first

Always create a follow-up PR to fix any bypassed checks.

推荐工作流

## Development Workflow

1. **Start work**
   ```bash
   git checkout main
   git pull
   git checkout -b feature/TICKET-123-new-feature
   ```

2. 进行变更

   # Make your changes
   git add .
   git commit -m "feat(api): add user search endpoint"
   

3. 保持更新

   git fetch origin
   git rebase origin/main
   

4. 推送并创建 PR

   git push origin feature/TICKET-123-new-feature
   # Create PR via GitHub/GitLab
   

5. 处理反馈

   # Make changes
   git add .
   git commit -m "fix: address review feedback"
   git push
   

6. 合并

   • 通过界面压缩并合并
   • 合并后删除分支

## Installation Checklist

- [ ] Commitlint config (commitlint.config.js)
- [ ] Git hooks (.husky/ or .git/hooks/)
- [ ] PR template (.github/pull_request_template.md)
- [ ] Branch protection rules (via GitHub settings)
- [ ] CI workflow for PR validation
- [ ] CONTRIBUTING.md with git guidelines
- [ ] .gitattributes for consistent line endings
- [ ] Emergency bypass documentation

## Best Practices

1. **Keep commits atomic**: One logical change per commit
2. **Write descriptive messages**: Explain why, not just what
3. **Reference tickets**: Include issue/ticket IDs
4. **Rebase before merging**: Keep history clean
5. **Review your own PR first**: Self-review catches many issues
6. **Respond to feedback promptly**: Don't leave PRs hanging
7. **Delete merged branches**: Keep repository tidy
8. **Use draft PRs**: For work-in-progress changes