Lib.rs

git-changelog 是一个生成变更日志（又称发布说明）的工具，这些日志通常在项目发布里程碑时分发。与其他执行相同功能的工具不同，这个工具不需要您遵循任何特定的 git 工作流程规范。它只假设您会挑选一些关键词（或使用内置的）来标注您的提交信息中的行。具体来说，一个 像这样 的提交生成一个 像这样 的输出。

当您想记录一个 用户可见 的变更（例如新功能、错误修复、破坏性变更等）时，您写下常规的提交信息，并在其中用您选择的关键词标注一些行。这些标注的行在报告生成时用于将变更组织到 分类 和 范围 中。组织好的变更随后被渲染为一个漂亮且准确的变更日志。

没有标签的提交信息将被默默地忽略，您可以自由地添加或省略标签。

这里有一个快速演示

动机

提交信息必须始终具有意义，并且通过一点额外的努力，我们可以自动化生成对用户有意义的变更日志的工作。当我完成一个变更的工作时，我喜欢停下来，思考这个变更对最终用户的意义，并稍微重新组织一下信息。如果您遵循以下（简单）规范并在提交信息中适当地标记行，这个工具将帮助您生成一个 准确 和 易于展示 的变更日志。

当变更的上下文和影响还清晰在脑中时，花点时间可以节省在发布里程碑时的很多时间。

安装

安装此工具的推荐方法是

> cargo install git-changelog

这将从源代码编译工具以适应您的环境。如果您只需要可执行文件，请参阅 发布。

如果您使用的是带有 Homebrew 的 Mac，您可以使用以下命令获取最新的二进制文件

> brew tap aldrin/tap
> brew install git-changelog

用法

像平常一样编写您的提交（或者 应该这样🙂）。当看起来特定的提交包含“用户”可能感兴趣的变化时，适当地标记其行。具体来说，而不是写这个

Add support for filtering responses

UI gets a bit cluttered when the response contains too many
items. Added a simple filtering scheme to reduce the result
set to a more relevant subset. Clients using v1.2 need to
upgrade to accomodate the new request parameter.

写这个

Add support for filtering responses

- feature: UI gets a bit cluttered when the response
  contains too many items. Added a simple filtering scheme
  to reduce the result set to a more relevant subset.

- break: Clients using v1.2 need to upgrade to accommodate
  the new request parameter.

两个提交信息几乎相同，但后者对用户可见的更改更加勤奋。最终，这种勤奋帮助工具识别行，汇总相似的内容（例如，破坏性更改）跨提交，对它们进行排序，并为您提供一份可以与他人分享的报告。或者，您可以将输出用作起始草案，进行编辑更改，然后与用户分享。无论哪种方式，都可以为您节省一些时间。

您不需要为每个提交都打上标签（例如，您认为它合适的地方，使用git commit -m就足够了）。您只需标记您希望用户了解的更改。

工具输出的质量取决于您输入的质量。

生成报告

一旦在PATH上，该工具就像一个常规的git子命令（例如，像git log）一样工作，并接受一个修订范围作为输入。它查看范围内的所有提交，并使用它们消息中找到的关键词生成报告。简单。😊

$ git changelog v0.1.1..v0.2.0

如果您没有提供修订范围，将使用<last-tag>..HEAD。如果没有定义标签，则仅选择最后一个提交。

$ git changelog -d
INFO: Reading file '/Users/aldrin/Code/git-changelog/.changelog.yml'
INFO: Using revision range 'v0.2.0..HEAD (15 commits)'
...

请注意，使用--可以了解工具的操作。

对于更复杂的范围选择，您可以像下面这样使用git log参数

$ git changelog -- --author aldrin --reverse --since "1 month ago"

在开始使用git log参数之前，请注意--。

自定义

每个项目都是不同的，您可能需要根据您的需求自定义标签和输出。

约定：您可以为您的项目定义更改类别和作用域标签以及标题。将一个.changelog.yml文件添加到您的仓库根目录（或使用--config选项）。请参阅默认配置文件以获取起始示例。

模板：如果您对输出不满意，可以指定自己的Handlebars模板。将一个.changelog.hbs添加到您的仓库根目录或使用--template命令行选项。请参阅默认模板以获取起始示例，以及库文档以了解输入数据结构的详细信息。

JSON：您可以使用--json标志完全跳过Markdown，并请求JSON输出。

后处理器：您可以向输出添加行后处理器以调整输出。我使用这些来简化向bug跟踪系统添加链接。例如，提交信息可以简单地说明票据号。

Fixes: JIRA-1234

然后，在配置文件中使用以下后处理器

output:
  post_processors:
    - {lookup: "JIRA-(?P<id>\\d+)", replace: "[JIRA-$id](https://jira.company.com/view/JIRA-$id)"}

该工具将其替换为

Fixes: [JIRA-1234](https://jira.company.com/view/JIRA-1234)