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 等。
阅读 222
84 声望
6 粉丝
0 条评论
84 声望
6 粉丝
文章目录
宣传栏