python git-cliff
# 聊聊 git-cliff：一个让版本日志变优雅的 Python 工具
如果你曾经维护过一个开源项目，或者参与过需要频繁发布版本的团队协作，一定对编写更新日志（Changelog）这件事不陌生。每次发布前，总要花时间整理提交记录，分类、归纳、排版，这个过程既繁琐又容易出错。今天想和大家分享一个能把这个过程自动化的工具：git-cliff。
它到底是什么
git-cliff 是一个用 Rust 编写但通过 Python 包分发的命令行工具。虽然核心是 Rust 实现的，但它在 Python 生态里的安装和使用体验很自然，通过 pip 就能直接安装。这个工具的主要作用是分析 Git 仓库的提交历史，然后根据预定义的规则自动生成结构化的更新日志。
你可以把它想象成一个智能的 Git 提交记录分析器。它不会简单地罗列所有提交信息，而是会识别提交信息中的特定模式（比如是否包含“feat:”、“fix:”这样的前缀），然后按照类型、作用域等维度对提交进行归类，最终生成一个格式统一、易于阅读的文档。
它能解决什么问题
最直接的用途当然是自动生成项目的更新日志。但它的价值不止于此。
很多团队在开发过程中会约定提交信息的格式（比如 Conventional Commits），但实际执行时总会有各种偏差。git-cliff 在生成日志时，其实也在间接推动团队遵守提交规范——因为只有符合规范的提交才能被正确归类展示。这种“温和的强制”比单纯的口头要求有效得多。
另一个不太明显但很有用的场景是版本管理。git-cliff 可以配合语义化版本（SemVer）自动建议下一个版本号。它会分析自上次发布以来的提交，如果有破坏性变更就建议主版本号升级，如果有新功能就建议次版本号，如果只是修复问题就建议修订号。这对维护者来说是个很实用的参考。
怎么把它用起来
安装很简单，一句pip install git-cliff就够了。不过真正要用好，得花点时间配置。
git-cliff 的行为由一个叫cliff.toml的配置文件控制。这个文件定义了如何解析提交信息、如何归类、输出什么格式等等。刚开始可以先用它的默认配置，生成一个基础的日志看看效果。
比如在项目根目录下运行git-cliff -o CHANGELOG.md，它会扫描所有提交记录，生成一个 Markdown 格式的更新日志。如果这是第一次使用，可能会发现输出不太理想，因为默认的规则可能不匹配项目的提交习惯。
这时候就需要调整配置了。打开cliff.toml，你会看到几个主要部分：[changelog]控制输出格式，[git]定义如何解析提交，[commit_parsers]是最关键的部分，它用正则表达式匹配提交信息并打上标签。
举个例子，如果你的团队用“feat”表示新功能，用“fix”表示问题修复，可以这样配置：
[[commit_parsers]] regex = "^feat" group = "Features" [[commit_parsers]] regex = "^fix" group = "Bug Fixes"这样所有以“feat”开头的提交都会归到“Features”部分，以“fix”开头的归到“Bug Fixes”部分。
更进阶的用法可以指定版本范围。比如git-cliff -o CHANGELOG.md --latest只生成自上次发布以来的变更，这在频繁发布的项目中特别有用。
一些实践中的经验
刚开始用 git-cliff 时，建议先花时间把团队的提交习惯梳理清楚。最好的方式是先收集一段时间内的真实提交记录，看看大家都怎么写提交信息，然后基于这些实际模式来设计匹配规则。这样比凭空制定规则更容易被接受。
配置文件最好纳入版本控制。这样团队每个成员都能生成一致的日志，也方便随着项目发展调整规则。可以把cliff.toml放在项目根目录，和代码一起维护。
生成日志的时机也值得考虑。有些团队在每次发布前手动运行，有些则集成到 CI/CD 流程中自动执行。后者更省心，但需要确保提交规范被严格遵守，否则自动生成的日志可能不准确。
还有个细节是忽略某些提交。比如那些“代码格式化”、“修正错别字”之类的提交，通常不需要出现在更新日志中。git-cliff 支持通过配置过滤这些提交，让最终生成的日志只包含对用户有实际影响的变更。
和其他工具的对比
提到自动生成更新日志，很多人会想到 standard-version 或 commitizen。这些工具各有侧重。
standard-version 更偏向“全自动”流程，它不仅能生成日志，还能自动更新版本号、打标签，适合希望完全自动化发布流程的团队。commitizen 则更注重提交时的引导和规范检查，它会在你提交时提示填写规范的提交信息。
git-cliff 的定位更纯粹一些：它专注于从已有的提交历史中提取信息并生成美观的日志。它不强制你在提交时使用特定工具，也不自动执行发布操作，就是做好“生成日志”这一件事。这种专注让它在某些场景下更灵活。
另一个对比是输出质量。git-cliff 默认的 Markdown 模板很简洁专业，而且支持自定义模板。如果你对日志的排版有特别要求，可以调整模板来匹配项目的文档风格。
选择哪个工具，其实取决于团队的工作流程和需求。如果已经有一套成熟的发布流程，只是需要自动化日志生成，git-cliff 的轻量和专注是优势。如果是从零开始建立规范，可能需要更全面的解决方案。
最后的一些想法
工具终究是工具，git-cliff 能减少编写更新日志的机械劳动，但它不能替代清晰的提交信息本身。无论用不用这个工具，养成写有意义的提交信息的习惯都是值得的。好的提交信息不仅是为了生成日志，更是为了几个月后回头看时，还能理解当初为什么这样修改。
git-cliff 的另一个启发是：很多看似需要人工判断的文档工作，其实可以通过简单的规则自动化。这种自动化不仅节省时间，还能保持一致性。在软件开发中，类似的机会可能还有很多，关键是有没有去发现和尝试。
如果你还没尝试过自动生成更新日志，不妨从 git-cliff 开始。即使最终不用它，配置过程中对团队提交习惯的梳理和反思，本身也是很有价值的。