Git 约定式提交

[!提示] 也可以看看 Git 约定式提交备忘单

更新日志

使用方法

npx git-conventional-commits <命令>

命令

ℹ 在命令后添加帮助参数 -h 可列出所有可用选项

  init [选项]                               创建配置文件模板 `git-conventional-commits.yaml`
  version [选项]                            根据约定式提交确定版本
  changelog [选项]                          根据约定式提交生成更新日志
  commit-msg-hook [选项] <commit-msg-file>  检查提交消息是否符合约定式格式

首次使用

运行 npx git-conventional-commits init
根据需要调整配置文件 git-conventional-commits.yaml

配置文件

git-conventional-commits.yaml 示例

---
convention:
  commitTypes:
  - feat
  - fix
  - perf
  - refactor
  - style
  - test
  - build
  - ops
  - docs
  - merge
  commitScopes: []
  releaseTagGlobPattern: v[0-9]*.[0-9]*.[0-9]*
changelog:
  commitTypes:
  - feat
  - fix
  - perf
  - merge
  includeInvalidCommits: true
  commitScopes: []
  commitIgnoreRegexPattern: "^WIP "
  headlines:
    feat: 功能
    fix: 错误修复
    perf: 性能优化
    merge: 合并
    breakingChange: 重大变更
  commitUrl: https://github.com/qoomon/git-conventional-commits/commit/%commit%
  commitRangeUrl: https://github.com/qoomon/git-conventional-commits/compare/%from%...%to%?diff=split
  issueRegexPattern: "#[0-9]+"
  issueUrl: https://github.com/qoomon/git-conventional-commits/issues/%issue%

convention
- commitTypes 预期的提交类型数组
  - 对意外类型显示警告
  - 如果未设置或为空，则禁用提交类型验证
  - 例如：["feat", "fix", "doc", "style"]
- commitScopes 预期的提交范围数组
  - 对意外范围显示警告
  - 如果未设置或为空，则禁用提交范围验证
  - 例如：["ui", "database"]
- releaseTagGlobPattern 用于过滤发布标签的通配符模式
  - 发布标签必须包含语义化版本号（[0-9]+\.[0-9]+\.[0-9]+）
  - 默认为 *
- issueRegexPattern 用于查找问题ID的正则表达式模式
  - 例如：Jira问题模式 [A-Z]{3,}-\\d+
changelog
- commitTypes 按类型过滤提交
  - convention.commitTypes 的子集，加上
    - merge 提交
  - 如果未设置或为空，则禁用提交类型过滤
  - 例如：["feat", "fix", "merge"]
- commitScopes 按范围过滤提交
  - convention.commitScopes 的子集
  - 如果未设置或为空，则禁用提交范围过滤
  - 例如：["ui"]
- includeInvalidCommits 包含没有有效类型的提交：默认为 true
  - 如果设置为false，所有未定义 commitTypes 的提交将从更新日志中移除
- commitIgnoreRegexPattern 通过提交主题正则表达式过滤提交
  - 默认为 ^WIP
- headlines 标题标识符和实际标题的映射
  - changelog.commitTypes 的子集，加上
    - breakingChange 重大变更部分
  - 例如：{ "feat": "功能", "fix": "错误修复", "breakingChange": "重大变更"}
  - 默认为 { "feat": "功能", "fix": "错误修复", "merge": "合并", "breakingChange": "重大变更"}
- commitUrl 用于生成指向仓库提交的Markdown链接的URL模板
  - %commit% 提交哈希占位符
  - 例如：https://github.com/qoomon/git-conventional-commits/commit/%commit%
  - 如果未设置或为空，则禁用链接生成
- issueUrl 用于生成指向问题跟踪器的Markdown链接的URL模板
  - %issue% 问题ID占位符
  - 例如：https://jira.example.org/browse/%issue%
  - 如果未设置或为空，则禁用链接生成

在提交前自动验证提交消息约定

为了自动验证提交消息，可以在 commit-msg 阶段使用git钩子。可以手动创建钩子，也可以使用 pre-commit 框架。

使用 pre-commit 框架设置

在仓库根目录创建 .pre-commit-config.yaml 文件，内容如下：

repos:
- repo: https://github.com/qoomon/git-conventional-commits
  rev: <RELEASE_TAG>
  hooks:
    - id: conventional-commits

安装 pre-commit 框架 pip install pre-commit
安装 commit-msg 钩子 pre-commit install -t commit-msg

手动设置

设置提交消息钩子
- 导航到您的仓库目录 cd <仓库路径>
- 创建 git 钩子目录 mkdir .git-hooks
- 设置更新 hooksPath git config core.hooksPath .git-hooks
- 创建提交消息钩子脚本并使其可执行
  - touch .git-hooks/commit-msg && chmod +x .git-hooks/commit-msg
  - 用您喜欢的编辑器打开 .git-hooks/commit-msg 并粘贴以下脚本
```
#!/bin/sh

# 针对 Windows 系统的修复
PATH="/c/Program Files/nodejs:$HOME/AppData/Roaming/npm/:$PATH"

npx git-conventional-commits commit-msg-hook "$1"
```
- 将 .git-hooks/commit-msg 添加并提交到仓库

[!重要] 每当您克隆带有 git 钩子的仓库时，您需要再次启用 git 钩子
git config core.hooksPath .git-hooks

### 使用 `git-conventional-commits` 的发布工作流程
* 通过 `npx git-conventional-commits version` 确定版本
* 更新项目文件中的版本
  * 提交版本更新 `git commit -am'build(release): 将项目版本升级到 <version>'`
* 通过 `npx git-conventional-commits changelog --release <version> --file 'CHANGELOG.md'` 生成变更日志
  * 提交变更日志 `git commit -am'docs(release): 创建 <version> 变更日志条目'`
* 用版本标记提交 `git tag -a -m'build(release): <version>' '<version-prefix><version>'`
* 推送所有更改 `git push`
* 构建并上传构件

### 与现有仓库集成

如果你有一个没有发布标签（如 v1.0.0）的大型现有仓库，或者你想让第一个变更日志整洁，你需要先创建一个发布标签。
* 为特定提交创建发布标签 `git tag -a -m'build(release): 0.0.0' 'v0.0.0'`
* 推送标签 `git push origin v0.0.0`
这样 `npx git-conventional-commits` 将只考虑发布标签所指向的提交之后的提交。

---
## 使用 git-conventional-commits 的项目
- https://github.com/Blazity/next-enterprise

---

## 构建/发布
* `npm install`
* `npm test`
* `npm login`
* `npm publish`