告别手动更新日志：用 git-cliff 自动从 Git 历史生成美观变更记录

你是否曾经在发布新版本时，面对着一大堆 Git 提交记录发愁？手动整理、归类、格式化这些提交信息，编写更新日志（changelog），既繁琐又容易出错。这个过程虽然必要，但很少有人真正喜欢去做。

想象一下，如果能够自动化这一过程，让更新日志直接从 Git 提交历史中自动生成，会怎样？这就是 git-cliff 要做的事情。

什么是 git-cliff？

git-cliff 是一个命令行工具，它能够根据你的 Git 历史生成美观且可定制化的更新日志。该工具使用 Rust 编写，以单个二进制文件发布，安装便捷，运行高效。

其核心能力在于对约定式提交（Conventional Commits）规范的支持。这意味着 git-cliff 可以智能解析你的提交信息，自动将不同类型的提交（例如 feat:、fix:、chore: 等）分类，并组织成清晰易读的文档。

简单来说，只要你按照一定的格式书写提交信息，git-cliff 就能自动将其转化为专业的更新日志，彻底告别手动复制粘贴提交哈希值的历史。

git-cliff 动画演示

为什么你应该尝试 git-cliff？

高度可定制化

如果你不喜欢默认的更新日志格式，完全没有关系。通过一个名为 cliff.toml 的配置文件，你可以灵活调整几乎所有输出细节：

  • 自定义页眉和页脚内容；
  • 调整提交的分组方式；
  • 修改日期显示格式；
  • 甚至编写自定义正则表达式，以解析特殊格式的提交信息。

这让你能完全控制更新日志的最终呈现形式，使其完美契合项目需求。

完美支持约定式提交

如果你的团队已经采用约定式提交（这是一种非常推荐的做法），那么 git-cliff 将成为你的得力助手。它能理解不同提交类型的语义，自动将 feat: 归类为“功能新增”，将 fix: 归类为“Bug 修复”，让更新日志结构清晰、一目了然。

过滤无关提交

并不是所有提交都需要出现在更新日志中。通过配置，你可以轻松忽略某些类型的提交（例如 chore: 或 ci:），确保最终生成的日志只包含对用户有实际意义的变更内容。

智能预置内容

默认情况下，git-cliff 会将新生成的更新日志内容添加到 CHANGELOG.md 文件的顶部——这正是你希望最新版本发布说明出现的位置。

如何安装 git-cliff？

安装 git-cliff 非常简便，你可以通过多种方式完成安装。

使用包管理器安装

如果你使用的是 macOS 或 Linux，推荐使用 Homebrew：

brew install git-cliff

Windows 用户则可以通过 Scoop 安装：

scoop install git-cliff

手动下载二进制文件

你也可以直接从 GitHub Releases 页面下载预编译好的二进制文件，解压后即可使用。

从源码构建

如果你希望从源码构建，请确保已安装 Rust 工具链，然后运行：

cargo install git-cliff

快速开始使用

安装完成后，进入你的 Git 项目目录，运行以下命令：

git cliff --latest

该命令会基于最近的 Git 标签生成更新日志内容。如果希望将输出直接写入 CHANGELOG.md 文件，可以添加输出参数：

git cliff --latest -o CHANGELOG.md

为了更好地适配你的项目，建议创建一个 cliff.toml 配置文件。官方文档提供了丰富的配置示例，帮助你快速上手。

配置示例：定制你的更新日志

以下是一个简单的 cliff.toml 配置示例，用于自定义头部和提交分组：

[changelog]
header = "# 更新日志"
body = """
## [{{ version }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {{ commit.message | upper_first }}
{% endfor %}
{% endfor %}
"""

通过类似这样的配置，你可以定义版本标题、日期格式、分组标题等内容，使更新日志完全符合项目风格。

常见问题解答（FAQ）

git-cliff 是否会覆盖我手动编写的更新日志？

默认情况下，git-cliff 会将新内容追加到现有文件的顶部，不会覆盖已有的旧版本日志。你仍然可以保留之前手动编写的内容。

如果我的提交信息不符合约定式提交规范怎么办？

git-cliff 仍然可以处理非规范的提交信息，但可能无法正确分类。你可以通过配置自定义正则表达式来解析特定格式的提交信息。

是否支持 mono-repo（单体仓库）？

是的，git-cliff 支持在 mono-repo 中使用，可以通过配置指定子目录或过滤特定路径的提交。

能否在 CI/CD 流程中自动运行？

完全可以。你可以在 GitHub Actions、GitLab CI 或其他持续集成工具中集成 git-cliff，使其在每次发布新标签时自动更新日志。

如果我需要中文化输出内容？

是的，通过自定义模板，你可以将更新日志的标题、分组名称等内容设置为中文或其他任何语言。

社区与资源

总结

git-cliff 是一款能够极大提升项目维护效率的工具。它充分利用约定式提交的优势，将规范化的提交信息转化为结构清晰、美观专业的更新日志，减少了手动操作带来的错误和重复劳动。

如果你重视项目的透明度和可维护性，希望为用户提供清晰的变更记录，那么 git-cliff 绝对值得你纳入开发流程。试着在下一个发布周期中使用它，你会发现，原来生成更新日志可以如此轻松。