git-cliff 变更日志生成指南：3 分钟让 Git 提交自动变 CHANGELOG.md

【免费下载链接】git-cliffA highly customizable Changelog Generator that follows Conventional Commit specifications ⛰️项目地址: https://gitcode.com/gh_mirrors/gi/git-cliff

每次打 tag 之前，都要翻提交记录手写 CHANGELOG.md：哪些是 feat、哪些是 fix、哪个 commit 对应哪条改动，全靠人肉归类。提交一多，日志就越来越旧。git-cliff 做的事正是把这段手工活接过去——读你的 Git 历史，按 Conventional Commits 把提交分组，渲染成一份格式化好的变更日志（changelog）。适合刚想给项目补上自动化发版记录的人，读完后能自己装好、配好，并生成第一份可用的 changelog。

手写 changelog 的痛点，基本都出在"分类"上

你大概率经历过这个场景：临近发版，git log拉出一百多条提交，fix、feat、chore混在一起，还要再想清楚哪些值得写进发布说明、链接该怎么填。手写一遍花半小时，下一个版本再来一遍。git-cliff 把"解析、分组、渲染"这三步都做成了配置，你的提交信息一旦写规范，日志就能直接出。

3 分钟装好并生成第一份 changelog

装一条命令就够（需要 Rust 工具链）：

cargo install git-cliff

在任意 Git 仓库根目录执行git cliff --init，会在当前目录生成默认的cliff.toml；不想从零改配置，也可以直接指定内置模板名，比如git cliff --init keepachangelog。

拿到配置文件后，真正要关心的项没几行：

• [git]段里conventional_commits = true：按 Conventional Commits 规范解析提交前缀，feat:、fix:都会被识别；
• commit_parsers = [...]：一组正则分组规则，决定feat进 Features、fix进 Bug Fixes；
• [changelog]的body：Tera 模板，控制日志长什么样，改这里就能换成自己的排版。

仓库自带的 cliff.toml 就是一份参考模板，可以边看边抄。然后：

git cliff -o CHANGELOG.md

终端不再打印时，当前目录多出一个 CHANGELOG.md：按 tag 版本分节，提交按解析器归组，带日期标题，直接可用。

发版前、版本号、格式不满意：三个高频场景

发版前只看不写。发布前想确认"这次会进日志的内容对不对"，跑git cliff --unreleased，只处理未打 tag 的提交，输出预览版；加--tag 1.0.0还能给它指定一个版本号。已有 CHANGELOG.md 时，git cliff --unreleased --tag 1.0.0 --prepend CHANGELOG.md会把新条目插到文件顶部而不是覆盖。

让工具顺手推导版本号。git cliff --bump会读未发版提交按 SemVer 升位：feat 升 MINOR，fix 升 PATCH，breaking change 升 MAJOR；加--bumped-version则只把算出的版本号打到标准输出、不改任何文件，适合在 CI 里直接拼进发布脚本。

格式不满意，先别改模板。git cliff --config detailed可以不用写配置文件，直接用内置模板名切换成"带 commit 链接"的详细版；git cliff --context能把解析出的数据导出成 JSON，喂给别的脚本自己渲染。

用下来发现这几件事值得注意

1. filter_unconventional默认true，不符合规范的提交会被静默丢弃。觉得日志"缺东西"时，先把它关掉跑一遍，看提交到底被分到了哪组。
2. tag_pattern决定哪些 tag 算正式发版，skip_tags排除 beta、alpha 这类预发布版本，两者的变更会并入下一个正式版本。
3. --prepend和-o指向同一文件时会互相冲突，--prepend会先移除旧的 header 再插入新条目。
4. 分组不对，先改commit_parsers：加一条正则就能把某类前缀归到新组，或用skip = true把 chore(deps) 这类提交彻底跳过。

和这些规范、工具搭配更顺

• Conventional Commits：提交前缀直接决定日志分组和版本升位，是这个方案的地基，建议团队统一遵守。
• SemVer：git cliff --bump推导的正是语义化版本号，feat/fix/breaking 分别对应 MINOR、PATCH、MAJOR。
• GitHub Actions：在 CI 里跑git cliff -o CHANGELOG.md，每次打 tag 自动更新日志，发版流程从此少一步人工。

更多参数细节可以看仓库里的 website/docs/usage/args.md 和 website/docs/configuration/。提交信息写得规范，剩下的交给 git-cliff 就行。

【免费下载链接】git-cliffA highly customizable Changelog Generator that follows Conventional Commit specifications ⛰️项目地址: https://gitcode.com/gh_mirrors/gi/git-cliff