git-cliff 2.4.0 新特性全解析Gitea 集成、可定制版本递增与模板上下文增强【免费下载链接】git-cliffA highly customizable Changelog Generator that follows Conventional Commit specifications ⛰️项目地址: https://gitcode.com/gh_mirrors/gi/git-cliff本指南围绕 git-cliff 2.4.0 版本发布的核心更新展开详细讲解 Gitea 远程集成、基于自定义正则的版本号递增--bump、可配置初始标签、--ignore-tags参数、Header 模板化、按 Footer 解析提交、标签消息支持以及模板上下文中新增的repository与远程数据变量。读完本文你将掌握如何配置并使用这些新能力让 changelog 生成与版本管理更加贴合团队的实际工作流。git-cliff 是一款用 Rust 编写的命令行工具能够从 git 历史中高度可定制地生成 changelog。它支持通过自定义正则表达式commit_parsers来改写主要基于 Conventional Commits 规范的提交信息借助单一 配置文件 与 Jinja2/Django 风格的模板引擎即可套用多种多样的 changelog 格式。2.4.0 版本在远程托管平台支持、版本号递增策略与模板上下文三个方向上带来了显著增强本文结合仓库源码逐项剖析这些特性。一、Gitea 集成新增第五种远程托管平台支持2.4.0 之前git-cliff 已支持 GitHub、GitLab、Bitbucket 与 Azure DevOps 四种远程平台本次更新新增了Gitea集成可以直接对接 Codeberg 或自建 Gitea 实例。从源码结构看远程模块位于 git-cliff-core/src/remote/其中 gitea.rs 定义了 Gitea 的 API 客户端实现GiteaClient通过 Gitea 的 REST API 分页拉取 commits 与 pull requestsgitea.rsAPI 端点形如{api_url}/api/v1/repos/{owner}/{repo}/commits与/pulls默认 API 地址为https://codeberg.org并可通过环境变量GITEA_API_URL覆盖gitea.rs这对于自建 Gitea 实例至关重要该模块声明了模板变量命名空间gitea、commit.gitea、commit.remotegitea.rs。启用 Gitea 集成后你可以在 changelog 模板中使用以下变量用户名${{ commit.gitea.username }}或${{ contributor.username }}贡献者列表${{ gitea.contributors }}Pull request${{ commit.gitea.pr_number }}或${{ contributor.pr_number }}由此可以生成如下风格的 changelog 条目## Whats Changed - feat(commit): add merge_commit flag to the context by orhun in #389 - test(fixture): add test fixture for bumping version by orhun in #360 ## New Contributors - someone made their first contribution in #360 - cliffjumper made their first contribution in #389 !-- generated by git-cliff --接入步骤为项目配置 Gitea 集成只需三步参考快速开始指南完成 git-cliff 的安装与初始化在配置文件的[remote.gitea]段设置 Git remoteowner/repo 信息更新 changelog 配置使用 Gitea 集成 中说明的模板变量。:::tip Gitea 集成与 GitHub 集成 的工作方式非常相似。对于使用自有 Gitea 实例的用户可通过GITEA_API_URL环境变量或配置文件中的api_url字段指定实例地址需要私有仓库访问时还可使用--gitea-token参数或GITEA_TOKEN环境变量提供访问令牌。 :::在 website/docs/integration/gitea.md 中可以看到完整的配置示例与gitea.contributors等上下文数据结构is_first_time字段配合filter(attributeis_first_time, valuetrue)过滤器即可筛选首次贡献者。二、基于自定义 pattern 的版本号递增Bump--bump参数默认按照 Conventional Commits 语义决定递增幅度fix:前缀 → 递增PATCHfeat:前缀 → 递增MINORscope!破坏性变更→ 递增MAJOR但实际项目中常有特殊的版本策略需求——例如希望以abc开头的提交触发 MAJOR 递增。2.4.0 起你可以通过配置自定义正则来接管递增规则[bump] custom_major_increment_regex abc custom_minor_increment_regex minor|more例如对于如下提交历史(HEAD - main) abc: 1 (tag: 0.1.0) initial commit由于存在以abc开头的提交MAJOR 被递增0.1.0变为1.0.0$ git-cliff --bumped-version 1.0.0在源码中Bump结构体完整定义于 config.rscustom_major_increment_regex与custom_minor_increment_regex均只针对提交类型commit type进行匹配且根据规范注释提交类型仅由[a-zA-Z]构成该结构体还包含no_increment_regex匹配到则不计递增与bump_type强制指定递增到 major/minor/patch等字段。命令行侧--bump与--bumped-version参数定义在 git-cliff/src/args.rs其中--bump支持auto/major/minor/patch取值。注意该命令需要开启 Conventional Commits 解析才能识别提交类型因此请确保配置中conventional_commits true。三、可配置的初始标签Initial Tag使用--bump时如果仓库中找不到任何标签此前默认版本会硬编码为0.1.0。这一默认值在源码中以常量形式存在DEFAULT_INITIAL_TAG: str 0.1.0config.rs。2.4.0 允许你在配置文件中覆盖它[bump] initial_tag 1.0.0也可以直接在命令行覆盖$ git-cliff --bump --tag1.0.0从实现上看Bump::get_initial_tag()config.rs会优先返回配置的initial_tag未配置时才回退到0.1.0默认值。对于从 0.x 起步或已有独立版本号体系的存量项目这一配置避免了首次 bump 与既有版本线不一致的问题。四、--ignore-tags命令行参数此前[git.ignore_tags]只能写在配置文件中2.4.0 新增了同名命令行参数允许在运行时覆盖配置值$ git-cliff --ignore-tags rc|v2.1.0|v2.1.1这等价于在配置文件中写入[git] # regex for ignoring tags ignore_tags rc|v2.1.0|v2.1.1该参数在 args.rs 中定义为--ignore-tags同时支持GIT_CLIFF_IGNORE_TAGS环境变量底层对应GitConfig.ignore_tags字段config.rs其语义是在tag_pattern筛选出候选标签之后进一步排除这些不应当作发布版本的标签。典型用途是过滤预发布标签如rc、beta或历史误打的标签避免它们干扰版本区间的划分与--bump计算。它和--skip-tags跳过整个仓库中匹配的标签的差异在于处理阶段不同实际使用时可根据从源头排除还是在候选集中剔除来选择。五、Header 模板化从纯文本到动态模板此前[changelog.header]只是拼接到 changelog 顶部的原始字符串2.4.0 起它与body、footer一样成为真正的模板可以使用模板变量与过滤器。例如在 Header 中动态生成版本区间注释[changelog] # template for the changelog footer header # Changelog {% for release in releases %}\ {% if release.version %}\ {% if release.previous.version %}\ !--{{ release.previous.version }}..{{ release.version }}-- {% endif %}\ {% else %}\ !--{{ release.previous.version }}..HEAD-- {% endif %}\ {% endfor %}\ 渲染结果为# Changelog !--v3.0.0..HEAD-- !--v0.2.0..v3.0.0-- !--v0.1.0..v0.2.0--从实现看ChangelogConfig.header与header_marker定义于 config.rs在 changelog.rs 中header 会被编译为Template渲染时按header releases footer的顺序拼接输出changelog.rs并且当 header 模板包含变量时会自动追加默认的header_marker!-- git-cliff: end of header --以便后续--prepend时精准定位并替换动态 header 部分。已知限制当时存在一个待修复的 issue--prepend与带变量的 header 模板配合时仍有问题升级到包含后续修复的版本可解决。六、按 Footer 解析提交精细化的提交过滤2.4.0 的commit_parsers新增了footer字段允许依据提交信息的footer脚注来匹配、分组或跳过提交。例如希望跳过带changelog: ignore脚注的提交git commit -m test: add more tests -m changelog: ignore配置如下[git] # regex for parsing and grouping commits commit_parsers [ { footer ^changelog: ?ignore, skip true }, ]实现层面commit parser 的匹配逻辑位于 commit.rs当 parser 声明了footer正则时会从该提交的 Conventional Commit 解析结果中提取所有 footers逐个用正则匹配如Signed-off-by: ...这类 token/value 结构见 commit.rs只有匹配成功该 parser 才生效。除了footercommit_parsers还支持message、body、fieldpattern、group、skip、replace等多种匹配与改写维度你可以在 commit.rs 中看到各字段的逐项校验流程。这一特性非常适合按脚注标记跳过某些提交如changelog: ignore、按脚注分组聚合提交等精细化场景。七、支持标签消息为每个版本添加标题行2.4.0 允许把发布标签的消息tag message纳入 changelog非常适合为每个版本撰写一段导语/标题## [1.0.1] - 2021-07-18 This is the release-tag message在模板上下文中标签消息通过{{ message }}变量访问{% if message %} {{ message }} {% endif %}\对于尚未打标签的未发布unreleased变更可以通过--with-tag-message参数临时指定消息$ git cliff --bump --unreleased --with-tag-message This is the release-tag message推荐的做法是为项目使用附注标签annotated tag来携带消息$ git tag v1.0.0 -m This is the release-tag message--with-tag-message参数定义于 args.rs支持GIT_CLIFF_WITH_TAG_MESSAGE环境变量在数据模型层面Release结构体持有可选的message字段release.rs模板渲染时即可直接读取。需要留意的是轻量标签lightweight tag没有独立消息因此只有附注标签才能提供该内容。八、模板上下文新增{{ repository }}变量多仓库场景下模板现在可以直接引用当前仓库路径## Release [{{ version }}] - {{ timestamp | date(format%Y-%m-%d) }} - {{ repository }}该变量来自Release.repository字段release.rs。当配合多仓库处理时特别有用例如$ git-cliff -r repo1 -r repo2此时生成的 changelog 可以清楚标明每个 release 来自哪个仓库避免多仓库合并输出时信息混淆。九、远程数据进入模板上下文2.4.0 还调整了 changelog 的处理顺序使得远程数据例如 GitHub 的提交、pull request 信息在模板渲染时立即可用。例如$ git cliff --github-repo orhun/git-cliff -c examples/github.toml --no-exec -u -x该命令输出的上下文中将包含 GitHub 数据例如github: { contributors: [ { username: bukowa, pr_title: style(lint): fix formatting, pr_number: 702, pr_labels: [], is_first_time: true }, ], }这意味着模板中可以直接使用${{ github.contributors }}、${{ commit.github.pr_number }}等变量来渲染贡献者名单PR 引用等内容无需再依赖后处理脚本。仓库中的 examples/github.toml 提供了配套的完整远程集成配置示例可在此基础上调整模板。同样的处理顺序改进同样作用于 Gitea、GitLab 等远程模块。十、其他改进网站文档补充了--bump与 tag 前缀tag prefixes配合使用的说明测试基础设施支持在 mingw64Windows环境下运行 fixtures提升了跨平台 CI 的覆盖能力。小结git-cliff 2.4.0 的核心价值在于三点更强的远程平台接入能力Gitea 集成让自托管/Codeberg 用户也能获得与 GitHub 集成一致的贡献者与 PR 数据、更灵活的版本号递增控制自定义正则与可配置初始标签让--bump适配任意版本策略、以及更丰富的模板上下文Header 模板化、标签消息、repository变量与远程数据前置配合--ignore-tags与按 Footer 解析提交可以让 changelog 的生成、过滤与版本计算完全纳入团队既有的工作流。完整的版本历史可在仓库根目录的 CHANGELOG.md 中查看最新配置项说明见 website/docs/configuration/模板语法与上下文结构详见 website/docs/templating/context.md。【免费下载链接】git-cliffA highly customizable Changelog Generator that follows Conventional Commit specifications ⛰️项目地址: https://gitcode.com/gh_mirrors/gi/git-cliff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考