3.3k Star！实用命令行工具，自动生成更新日志文件

【导语】：基于 Git 历史记录自动生成日志变更文件。

简介

git-cliff 可用正常提交记录以及基于正则的自定义解析，从 Git 历史记录生成 changelog 文件，变更日志模板可以使用配置文件进行定制，以匹配所需的格式。

类似的项目还有：

git-journal - Git 提交消息和变更日志生成框架
clog-cli - 从 Git 提交历史生成漂亮的变更日志
relnotes - 为项目自动生成发行说明的工具
cocogitto - 用于常规提交和 semver 规范的 CLI 工具

项目地址：

https://github.com/orhun/git-...

安装

从 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 等。