Git-Cliff工具处理非规范提交时的注意事项

在软件开发过程中，版本变更日志(Changelog)的生成是项目维护的重要环节。Git-Cliff作为一款基于Git历史的变更日志生成工具，其默认配置会过滤掉不符合约定式提交(Conventional Commits)规范的提交信息。本文通过一个实际案例，分析Git-Cliff在处理非规范提交时的行为表现及解决方案。

问题现象分析

在某个使用Git-Cliff生成变更日志的项目中，开发者发现一个重要提交"Add horizontal scrollbars and hide scrollbars if there is enough space (#30)"未被包含在生成的变更日志中。该提交虽然包含功能描述和问题编号，但缺少约定式提交规范要求的前缀(如feat:、fix:等)。

检查项目配置发现filter_unconventional = false已设置为不过滤非规范提交，但该提交仍然缺失。这表明Git-Cliff的处理逻辑可能存在某些特殊情况。

技术背景

约定式提交规范要求提交信息遵循特定格式：

<类型>[可选的作用域]: <描述>

[可选的正文]

[可选的脚注]

Git-Cliff默认会：

1. 解析Git历史记录
2. 根据配置过滤提交
3. 按类型分类提交
4. 生成格式化变更日志

解决方案

对于需要包含非规范提交的项目，建议采取以下措施：

1. 配置调整： 确保配置文件中包含：

   [git]
   filter_unconventional = false
   

2. 提交信息规范化： 即使允许非规范提交，也建议遵循约定式提交规范。例如将示例提交改写为：

   feat: add horizontal scrollbars and hide when enough space (#30)
   

3. 历史提交重写： 对于已存在的非规范提交，可以使用交互式变基(rebase)重写提交信息：

   git rebase -i HEAD~10
   

最佳实践建议

1. 在项目早期建立提交规范
2. 使用Git钩子验证提交信息格式
3. 定期检查生成的变更日志是否完整
4. 对于重要但不符合规范的提交，及时进行修正

通过合理配置和规范使用，Git-Cliff能够成为项目版本管理中的得力助手，准确反映项目的变更历史。