git-cliff：从 Git 提交记录自动生成可定制变更日志的开源工具

获取下载链全程约 1 分钟

1. 打开微信，搜索「软件教程管家」关注，或长按下方二维码关注
2. 回复关键词 git-cliff 复制关键词
3. 公众号自动回复网盘链接，点击即可保存下载

打开微信扫一扫关注
或搜索【软件教程管家】

官方渠道：GitHub 仓库

每次发版前手动整理变更日志，是很多开发团队最容易拖延的一件事：提交记录明明都在仓库里，却要靠人一条条翻、分类、排版。git-cliff 就是为解决这个问题而生的开源工具——它直接读取 Git 历史，按 Conventional Commits 规范或自定义正则把提交分类，再套用模板生成格式统一的 changelog。本篇讲清 git-cliff 的安装方式、cliff.toml 的 4 个必改配置和从生成到发布的完整命令链，帮你把变更日志变成发版流程里自动跑的一步。

版本与安装包选择：先给结论

结论：只是想用起来，优先用包管理器或 Releases 页的预编译包；Rust 开发者或需要最新构建时再走 cargo 安装。三种方式装出来的是同一个二进制，区别只在升级成本和对网络的要求。

安装步骤

1. 按上表选一种安装方式：macOS 执行 brew install git-cliff；Arch Linux 执行 pacman -S git-cliff；Windows 或其他系统去 Releases 页下载对应平台的预编译包并解压到 PATH 目录；已装 Rust 工具链的也可以执行 cargo install git-cliff。
2. 在终端执行 git cliff –version，能打印出版本号即安装成功；若提示找不到命令，先检查预编译包解压路径是否已加入 PATH。
3. 进入已有 Git 历史的项目目录，执行 git cliff –init，在项目根目录生成一份默认的 cliff.toml 配置文件。
4. 执行 git cliff -o CHANGELOG.md 生成第一份变更日志，打开文件核对分组与格式是否符合预期，再按下一节调整配置。

装完必改的 4 个配置

默认配置只能跑通流程，真正好用的 changelog 都靠 cliff.toml 调出来。入口路径：项目根目录下的 cliff.toml 文件，改完保存后重新生成即生效。

• commit_parsers：提交分类规则。在 [git] 段的 commit_parsers 里按 message 正则把提交分进 Features、Bug Fixes 等分组，并用 skip 把 chore、style 这类不需要进日志的提交排除。体感差别：改之前日志是按时间平铺的提交流水账，改之后是一份按类型分组、可直接读的发布说明。
• tag_pattern：版本范围匹配。默认匹配 v 开头的数字标签，如 v[0-9]*。如果你的项目标签不带 v 前缀或用其他命名规则，必须先改这一项，否则 git cliff 会找不到版本边界，把全部历史打进同一份日志。
• 模板：输出格式。在 [changelog] 段的 body 模板里定每一组的标题、提交行的写法和链接格式，模板使用 Tera 语法。体感差别：默认模板偏简洁，改成带提交链接和 issue 引用的模板后，日志里的每条记录都能点回原始提交，出了问题可追溯。
• conventional_commits 与 filter_commits：解析口径。conventional_commits 设为 true 时按 Conventional Commits 规范解析，filter_commits 则只保留符合解析规则的提交。体感差别：团队提交规范执行得越严，这一项开着越省心；提交比较随意时，先关掉严格过滤、配合自定义正则解析器兜底，比直接丢弃提交更稳妥。

常用命令：从生成到发布

日常使用基本围绕下面几条命令，发布流程里按顺序串起来即可：

git cliff --init                  # 生成默认配置文件 cliff.toml
git cliff -o CHANGELOG.md         # 生成完整变更日志并写入文件
git cliff --unreleased            # 只生成尚未打标签的提交
git cliff --tag v1.0.0            # 生成到指定版本为止的日志
git cliff --bump                  # 按提交类型自动推断下一个版本号
git cliff --prepend CHANGELOG.md  # 把新版本日志追加到已有文件开头
git cliff --with-commit abc1234   # 把某次提交包含进本次生成范围

推荐的发版串联方式：打标签前先跑 git cliff –unreleased 预览本次要发布的内容，确认无误后打标签，再用 git cliff –prepend CHANGELOG.md 把新版本写进日志文件顶部，随代码一起提交。

注意事项

• 生成质量取决于提交质量。git-cliff 不会替你写提交信息，提交写得随意，生成的日志就只能按正则兜底分类。团队先统一提交约定再接入，效果才有保障；接入前建议先对历史提交跑一遍生成结果抽查。
• 先在副本或分支上验证配置。改模板、改分组规则后，先用 git cliff –unreleased 预览输出，确认分组和链接无误再写进正式的 CHANGELOG.md，避免把格式错误的日志提交进主分支。
• 配置文件要进版本控制。cliff.toml 和自定义模板是团队共识的一部分，应随代码一起提交；只在本地改配置不提交，换台机器或换人接手时生成结果就会对不上。
• Monorepo 场景先看文档再动手。项目说明提到具备 monorepo 相关能力，但多包仓库的范围划分、标签策略需要结合文档配置，不建议直接按单仓库的默认配置套用。
• Windows 用户注意终端编码。预编译包在 PowerShell 与 CMD 下均可运行，日志含中文提交时建议用 UTF-8 编码的终端查看，避免输出出现乱码。

适合谁 / 不适合谁

适合：已经采用 Conventional Commits 的开发团队；需要把变更日志纳入 CI 发版流程的项目维护者；同时维护多个版本分支、希望日志格式长期统一的开源项目。

不适合：提交信息完全自由发挥、短期内不打算统一提交规范的团队——先花成本把提交约定立起来，再接入工具，否则生成结果需要大量手工修补。

同类工具对比：clog-cli、cocogitto、release-plz 等也覆盖提交转日志的需求，git-cliff 的差异点在于模板与正则解析器的定制空间更大，且不绑定特定语言生态；如果你要的是开箱即用的固定格式，其他工具可能更快，如果要的是完全按自家格式输出，git-cliff 更合适。项目还提供 Emacs 支持 git-cliff.el，Emacs 用户可以在编辑器内完成生成与发布。

获取

访问 GitHub 仓库

GitHub 国内访问较慢，如打不开可多刷新几次

推广

关注「软件教程管家」

回复软件名即取即下：网盘下载链接 + 提取码，一步直达，不用再跳转。

相关推荐

开发git-branchless 免费下载｜撤销工具开发GitHub Desktop 3.6.7 绿色版下载开发SmartGit 26.1 中文版下载｜图形化Git客户端开发Gerrit：面向 Git 项目的代码评审与项目管理工具开发MyGit Git 免费下载｜AI编程，轻量原生开发aiwli Git 免费下载