Git-Cliff 2.14.0 发布：破坏性 CLI 变更，HN 却无人问津

多源交叉验证与社区反差

有个数字让我愣了一下。git-cliff 2.14.0 的发布帖在 Hacker News 上得 1 分，评论数是 0 来源：HN。而发布博客开头写的是一句意气风发的“So many things...” 来源：git-cliff 博客。一边是开发者的兴奋，一边是社区近乎完全的沉默。发布帖挂在 HN 上，通常意味着有人觉得值得讨论。这次没有。

我顺着博客里的完整 changelog 链接翻进去，记录得相当细。自动配置发现、模板目录和 body 模板文件分别对应 #1584、#1583、#1574 来源：git-cliff 博客。新功能的每一步都有 issue 讨论轨迹。交叉验证之后，我对这个反差有了个基本判断。工具类项目的小版本发布，在 HN 上往往得不到多少目光，但这不是发布质量的衡量标准。

真正值得在意的，是博客里那块被醒目标出的迁移指南。它提醒我，这次升级里有破坏性变更。如果你的脚本还在用旧写法，升级前最好把迁移指南从头读到尾 来源：git-cliff 博客。

破坏性变更藏在参数行为里

这次最需要留神的，是 --include-path、--exclude-path、--with-commit 和 --skip-commit 四个选项。它们过去可以一次吃进多个值，比如 git cliff --include-path "src/**" "docs/**"，现在必须每个值单独写一遍选项。git cliff --include-path "src/**" --include-path "docs/**" 来源：git-cliff 博客。这个变化在博客里被放在 Migration Guide 标题下，位置很显眼。

改动的理由写在第 #1614 号 issue 里。旧的解析方式会把尾部的位置范围误当成另一个选项值，导致 changelog 的起止提交被吞掉。新行为让每个选项只消费一个值，位置范围可以放在前面，也可以写成引号包住的空格分隔串 来源：git-cliff 博客。

这种变更在迁移指南里被单独标出来，说明官方认为升级者得主动看一眼。我不确定 git-cliff 会不会在旧写法下给出警告，但脚本里带多个路径参数的人，升级后值得跑一遍 diff 确认输出没变 来源：git-cliff 博客。

Rust API 和打包者的连带账

如果你在 Rust 项目里把 git-cliff 当库用，这次有两笔账要还。Opt::config 从 PathBuf 变成了 Option，公开的 changelog 和 remote context 类型也加了新字段，用 struct 字面量构造的代码必须补上这些字段 来源：git-cliff 博客。

另一个变化在底层。git-cliff-core 把 git2 升级到 0.21，libgit2 的 SONAME 也跟着变。从源码构建现在要求 Rust 1.88.0 或更新，动态链接的包必须对着新版本 libgit2 重新构建 来源：git-cliff 博客。

这两个信息对普通用户可能无所谓，但对发行版打包者和持续集成维护者，属于必须在升级计划里写进去的项目。SONAME 变更意味着系统里旧的动态库文件不会自动兼容，依赖链上任何一个环节没跟上，运行时就是链接错误。

新功能在回答旧问题

破坏性变更之外，这次也加了几样有用的东西。配置文件现在能自动发现，省略 --config 时 git-cliff 会自己找（#1584）来源：git-cliff 博客。模板方面，你可以把自己写的模板放进一个目录，用 --templates-dir 指定，再用 --init 按名字初始化，--list-templates 能看到内置和自定义的全部模板（#1583）来源：git-cliff 博客。这些功能把配置从命令行参数里挪了出来。

还有个细节值得说。--body 参数过去只能传一行字符串，多行模板得靠转义或外部变量。2.14.0 加了 --body-file，直接把 changelog 主体模板放到文件里，比如 git cliff --body-file changelog-body.tera（#1574）来源：git-cliff 博客。

我的判断是，配置文件、模板文件都能进版本库，比把一大串参数写进 Makefile 好维护。下一步它会不会把更多参数挪进文件，我不确定，但这一步走得对。

原文：

Git-Cliff 2.14.0 · 来源：Hacker News

作者：itfan123 值班编辑 · 发布于 2026年10月28日