深入解析git-cliff项目中的scopesorted.toml配置

深入解析git-cliff项目中的scopesorted.toml配置

git-cliff A highly customizable Changelog Generator that follows Conventional Commit specifications ⛰️ 项目地址: https://gitcode.com/gh_mirrors/gi/git-cliff

什么是git-cliff

git-cliff是一个强大的变更日志生成工具，它能够根据Git仓库的提交历史自动生成结构化的变更日志。这个工具特别适合遵循常规提交规范(Conventional Commits)的项目，能够自动分类和组织提交信息，生成专业级的变更日志文档。

scopesorted.toml配置文件解析

scopesorted.toml是git-cliff的一个示例配置文件，它展示了如何通过配置生成一个按作用域(scope)排序的变更日志。下面我们来详细分析这个配置文件的各个部分。

changelog配置块

[changelog]部分定义了变更日志的生成模板和格式：

1. header：定义了变更日志的头部内容，通常包含项目说明和文件用途
2. body：定义了每个版本变更日志的主体模板，这是最复杂的部分
3. footer：定义了变更日志的页脚内容
4. trim：控制是否去除生成内容中的前后空白字符

body模板详解

body模板使用了Tera模板引擎，它包含以下关键功能：

1. 版本标题处理：根据是否有版本号显示不同的标题格式

   {% if version %}## {{ version | trim_start_matches(pat="v") }} - {{ timestamp | date(format="%Y-%m-%d") }}
   {% else %}## Unreleased{% endif %}
   

2. 提交分组处理：将提交按组(group)分类，并转换为首字母大写的组名

   {% for group, commits in commits | group_by(attribute="group") %}
   ### {{ group | upper_first }}
   

3. 作用域排序：对每个组内的提交按作用域(scope)排序

   {% for commit in commits | filter(attribute="scope") | sort(attribute="scope") %}
   

4. 提交信息格式化：格式化每条提交信息，包括作用域和提交消息

   - *({{commit.scope}})* {{ commit.message | upper_first }}
   

5. BREAKING变更处理：特别标记重大变更(BREAKING CHANGE)

   {% if commit.breaking %}  - **BREAKING**: {{commit.breaking_description}}{% endif %}
   

6. 无作用域提交处理：处理没有作用域的提交，标记为"No Category"

   {% if commit.scope %}{% else %}- *(No Category)* {{ commit.message | upper_first }}
   

git配置块

[git]部分定义了如何处理Git提交历史：

1. conventional_commits：启用常规提交规范解析
2. filter_unconventional：过滤不符合常规提交规范的提交
3. commit_parsers：定义了一系列正则表达式解析器，用于：
   • 将提交分配到不同的组(如Features、Bug Fixes等)
   • 跳过特定提交(如发布准备提交)
   • 根据提交正文内容分类(如安全相关提交)
4. filter_commits：是否过滤未被任何解析器匹配的提交
5. topo_order：是否按拓扑顺序而非时间顺序排列发布
6. sort_commits：提交在每组/每个版本中的排序方式(最旧或最新)

实际应用场景

这种配置特别适合以下场景：

1. 大型项目：需要清晰分类和组织大量提交
2. 多模块项目：通过作用域(scope)区分不同模块的变更
3. 严格遵循常规提交规范的项目：能够充分利用git-cliff的自动化分类能力
4. 需要突出重大变更的项目：BREAKING CHANGE会被特别标记

最佳实践建议

1. 保持提交规范：确保团队遵循常规提交规范，以获得最佳效果
2. 合理使用作用域：为相关提交添加适当的作用域，增强变更日志的可读性
3. 定期生成变更日志：在每次发布前生成并审查变更日志
4. 自定义模板：根据项目需求调整模板，使其更符合项目风格
5. 处理BREAKING CHANGE：确保重大变更描述清晰完整

通过合理配置git-cliff的scopesorted.toml文件，项目可以自动化生成专业、结构清晰的变更日志，大大减轻维护负担，提高项目的专业性和透明度。

git-cliff A highly customizable Changelog Generator that follows Conventional Commit specifications ⛰️ 项目地址: https://gitcode.com/gh_mirrors/gi/git-cliff