# Git Conventional Commit Messages

> Git 约定式提交规范 — commit message 格式、类型、规则。Use when writing Git commit messages, conventional commits format.

- Skill: `liaosw97/git-conventional-commit-messages` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add liaosw97/git-conventional-commit-messages`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liaosw97/git-conventional-commit-messages/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: liaosw97 (https://skillmd.com/u/liaosw97)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/liaosw97/git-conventional-commit-messages

---


## 核心原则
- 使用约定式提交（Conventional Commits）规范
- 保持提交信息清晰、简洁、有意义
- 每个提交应该只做一件事
- 提交信息应解释"为什么"而不仅是"做了什么"

## 技术栈
- **版本控制**：Git
- **规范**：Conventional Commits
- **工具**：commitlint, standard-version, semantic-release
- **CI/CD**：GitHub Actions / GitLab CI

## 最佳实践
### 提交消息格式

```
<类型>[可选范围]: <描述>

[可选正文]

[可选页脚]
```

### 类型说明

| 类型 | 描述 | 版本影响 |
|------|------|----------|
| `feat` | 新功能 | MINOR |
| `fix` | Bug 修复 | PATCH |
| `docs` | 文档更新 | - |
| `style` | 代码格式（不影响逻辑） | - |
| `refactor` | 重构（不修复 Bug 也不添加功能） | - |
| `perf` | 性能优化 | PATCH |
| `test` | 添加或修改测试 | - |
| `build` | 构建系统或依赖更新 | - |
| `ci` | CI 配置修改 | - |
| `chore` | 其他不修改 src 的更改 | - |

### 示例

```bash
# 简单提交
feat: 添加用户登录功能

# 带范围的提交
feat(auth): 添加 OAuth2.0 认证支持

# 带 Breaking Change
feat(api)!: 重构 API 响应格式

BREAKING CHANGE: API 响应现在使用 { data, meta } 结构

# 带 Issue 引用
fix: 修复用户头像上传问题

Closes #123
```

### 正文规范

1. 使用祈使语气："添加"而非"添加了"
2. 首字母大写
3. 不以句号结尾
4. 限制首行 72 字符以内
5. 正文说明更改的动机和对比

## 关键约定
1. **破坏性变更**

```
feat!: 移除旧版 API

BREAKING CHANGE: 所有 /v1/* 端点已被移除，请迁移至 /v2/*
```

2. **多 Issue 关联**

```
feat: 添加批量导出功能

Implements #100, #101
Related to #99
```

3. **Code Review 建议**

```
refactor: 优化数据库查询性能

根据性能测试结果，将 N+1 查询优化为批量查询：
- 使用 select_related 减少 SQL 查询次数
- 添加数据库索引提升查询速度

Benchmark 结果：响应时间从 2s 降至 200ms
```

4. **版本发布**

```bash
# 使用 standard-version 自动生成 CHANGELOG
npm run release      # 补丁版本
npm run release:minor # 次版本
npm run release:major # 主版本
```

## 配置示例
### commitlint.config.js

```javascript
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore']
    ],
    'subject-max-length': [2, 'always', 72]
  }
};
```

### .husky/commit-msg

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

npx --no -- commitlint --edit "$1"
```

## 工作流集成
### GitHub Actions

```yaml
name: Lint Commit Messages
on: [push, pull_request]

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: wagoid/commitlint-github-action@v5
```

## 参考资料
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Angular Commit Guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit)
- [semantic-release](https://semantic-release.gitbook.io/)