Git 约定式提交

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

更新日志

查看 CHANGELOG.md

使用方法

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 钩子 <br>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`