【导语】：基于 Git 历史记录自动生成日志变更文件。
简介
git-cliff 可用正常提交记录以及基于正则的自定义解析，从 Git 历史记录生成 changelog 文件，变更日志模板可以使用配置文件进行定制，以匹配所需的格式。
类似的项目还有：
- git-journal - Git 提交消息和变更日志生成框架
- clog-cli - 从 Git 提交历史生成漂亮的变更日志
- relnotes - 为项目自动生成发行说明的工具
- cocogitto - 用于常规提交和 semver 规范的 CLI 工具
项目地址：
https://github.com/orhun/git-cliff
安装
从 crates.io 进行安装
cargo install git-cliff
使用 pacman
pacman -S git-cliff
从源码构建
# linux 下依赖 zlib，生成的文件存放在 `target/release/git-cliff` 目录
CARGO_TARGET_DIR=target cargo build --release
用法
命令格式
git-cliff [FLAGS] [OPTIONS] [RANGE]
例子
使用 --init 选项可以生成默认的配置文件 cliff.toml
git cliff --init
在项目的根目录下，可以很简单地生成 changlog 文件：
# 等价于 `git-cliff --config cliff.toml --repository .`
# 等价于 `git-cliff --workdir .`
git cliff
打 tag：
git cliff --tag 1.0.0
为 git 历史的某个部分生成 changelog：
# 为 latest tag 生成 changelog
git cliff --latest
# 为未发布的内部生成 changelog
git cliff --unreleased
git cliff --unreleased --tag 1.0.0
# 为指定的某个 commit 生成 changelog
git cliff 4c7b043..a440c6e
git cliff 4c7b043..HEAD
git cliff HEAD~2..
指定生成某个目录的 changelog：
git cliff --commit-path project1/
将 changelog 保存到指定文件中
git cliff --output CHANGELOG.md
将新变更追加到 changelog 中：
git cliff --unreleased --tag 1.0.0 --prepend CHANGELOG.md
配置文件
git-cliff 配置文件支持 TOML（首选）和 YAML 格式。
如果 $HOME/git-cliff/cliff.toml 文件存在，则从配置文件中读取。此位置取决于不同的平台，例如：
# 在 Linux 上： /home/<user>/.config/git-cliff/cliff.toml
# 在 Windows 上：C:\Users\<user>\AppData\Roaming\git-cliff\cliff.toml
# 在 macOS 上： /Users/<user>/Library/Application Support/git-cliff/cliff.toml
changelog
changelog 生成的配置选项如下：
[changelog]
header = "Changelog"
body = """
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {{ commit.message | upper_first }}
{% endfor %}
{% endfor %}
"""
trim = true
footer = "<!-- generated by git-cliff -->"
- header，changelog 的标题
- body，changelog 中的主体模板
- trim，如果设置为 true，将删除文本中前导和尾随空格
- footer，changelog 的页脚文本
git
git 相关的配置选项：
[git]
conventional_commits = true
commit_parsers = [
{ message = "^feat", group = "Features"},
{ message = "^fix", group = "Bug Fixes"},
{ message = "^doc", group = "Documentation"},
{ message = "^perf", group = "Performance"},
{ message = "^refactor", group = "Refactor"},
{ message = "^style", group = "Styling"},
{ message = "^test", group = "Testing"},
]
filter_commits = false
tag_pattern = "v[0-9]*"
skip_tags = "v0.1.0-beta.1"
conventional_commits
如果设置为 true，则根据约定式提交规范进行解析提交。规范参考下面链接地址：
https://www.conventionalcommits.org/en/v1.0.0/
约定式提交规范是一种基于提交信息的轻量级约定。提供一组简单规则来创建清晰的提交历史；这有利于编写自动化工具。通过在提交信息中描述功能、修复和破坏性变更，使这种惯例与 SemVer 相互对应。
提交说明的结构如下所示：
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
# 如：feat(parser): add ability to parse arrays
commit_parsers
提交解析器，用于使用正则表达式确定提交组：
# 如果提交消息以“feat”开头，则将提交分组为“Features”。
{ message = "^feat", group = "Features"}
# 如果提交正文包含“security”，则将提交分组为“Security”。
{ body = ".*security", group = "Security"}
# 如果提交正文和消息包含“deprecated”，则将提交分组为“Deprecation”
{ message = ".*deprecated", body = ".*deprecated", group = "Deprecation"}
# 如果提交消息（描述）以“revert”开头，则跳过处理提交。
{ message = "^revert", skip = true}
# 如果提交以“doc”开头，则将提交分组为“Documentation”
{ message = "^doc", group = "Documentation", default_scope = "other"}
filter_commits
如果设置为 true，则提交解析器不匹配的提交将被过滤掉。
tag_pattern
用于匹配 git 标签的 glob 模式。例如，它处理与以下 git 命令的输出相同的标签：
git tag --list 'v[0-9]*'
skip_tags
用于跳过处理匹配标签的正则表达式。
开源前哨日常分享热门、有趣和实用的开源项目。参与维护 10万+ Star 的开源技术资源库，包括：Python、Java、C/C++、Go、JS、CSS、Node.js、PHP、.NET 等。
