git-chglog

用Go（Golang）实现的CHANGELOG生成器。 随时随地，编写你的CHANGELOG。

目录

• git-chglog
  • 目录
  • 特性
  • 工作原理
  • 入门指南
    • 安装
      • Homebrew（适用于macOS用户）
      • Scoop（适用于Windows用户）
      • asdf
      • Go用户
    • Docker
    • 测试安装
    • 快速开始
  • CLI使用
    • tag查询
  • 配置
    • bin
    • style
    • template
    • info
    • options
      • options.sort
      • options.commits
      • options.commit_groups
      • options.header
      • options.issues
      • options.refs
      • options.merges
      • options.reverts
      • options.notes
  • 模板
  • 支持的样式
  • Jira集成
    • 1. 在配置文件中更改头部解析模式以识别Jira问题ID
    • 2. 在配置文件中添加Jira配置
    • 3. 更新模板以显示Jira数据
  • 常见问题
  • 待办事项
  • 致谢
  • 贡献
  • 开发
  • 发布流程
  • 反馈
  • 更新日志
  • 相关项目
  • 许可证

特性

• :recycle: 高度可移植性
  • 它以单一二进制文件工作。因此，可以用于任何项目（环境）。
• :beginner: 简单易用
  • CLI使用非常简单，学习成本低。
  • 例如，最简单的命令是$ git-chglog。
• :rocket: 高度灵活
  • 提交信息格式和...
  • CHANGELOG的样式（模板）和...
  • 等等...

工作原理

git-chglog内部使用git命令来获取要包含在CHANGELOG中的数据。基本步骤如下。

1. 获取所有标签。
2. 获取tagA和tagB之间包含的提交。
3. 对应步骤1和2中指定的tag查询的所有标签执行。

入门指南

我们将从安装开始，介绍直到自动生成配置文件和模板的步骤。

安装

请以适合您环境的方式安装git-chglog。

Homebrew（适用于macOS用户）

brew tap git-chglog/git-chglog
brew install git-chglog

Scoop（适用于Windows用户）

scoop install git-chglog

asdf

asdf plugin-add git-chglog https://github.com/GoodwayGroup/asdf-git-chglog.git
asdf install git-chglog latest

Go用户

go install github.com/git-chglog/git-chglog/cmd/git-chglog@latest

Docker

编译好的docker镜像维护在quay.io上。 我们维护以下标签：

• edge：从主分支的当前HEAD构建的镜像。
• latest：从最新发布版本构建的镜像。
• x.y.y（版本）：从Github中标记的版本构建的镜像。

docker pull quay.io/git-chglog/git-chglog:latest
docker run -v "$PWD":/workdir quay.io/git-chglog/git-chglog --version

---

如果您使用其他平台，可以从[releases页面]下载二进制文件，并将其放置在$PATH中的目录中。

测试安装

您可以使用以下命令检查 git-chglog 命令是否已包含在您的 $PATH 目录中。

$ git-chglog --version
# 输出 git-chglog 版本

快速开始

git-chglog 需要配置文件和模板来生成 CHANGELOG。

然而，从头开始创建配置文件和模板是浪费时间的。

因此，我们建议使用 --init 选项，它将交互式地创建它们 :+1:

git-chglog --init

---

现在您已经准备好配置文件和模板了！

让我们立即生成您项目的 CHANGELOG。 通过执行以下简单命令，CHANGELOG 的 Markdown 内容将显示在标准输出中。

git-chglog

如果您想输出到文件而不是标准输出，请使用 -o（--output）选项。

git-chglog -o CHANGELOG.md

---

现在您已经了解了 git-chglog 的基本用法！

为了制作更好的 CHANGELOG，请参考以下文档并进行自定义。

CLI 用法

$ git-chglog --help

用法：
  git-chglog [选项] <标签查询>

    <标签查询>有以下几种指定方法：

    1. <旧>..<新> - 包含在 <旧> 标签到 <新> 标签之间的提交。
    2. <名称>..   - 从 <名称> 到最新标签的提交。
    3. ..<名称>   - 从最早的标签到 <名称> 的提交。
    4. <名称>     - 包含在 <名称> 中的提交。

选项：
  --init                      以交互方式生成 git-chglog 配置文件（默认：false）
  --path value                按路径过滤提交。可多次使用。
  --config value, -c value    指定不同的配置文件（默认：".chglog/config.yml"）
  --template value, -t value  指定模板文件。如果未指定，使用配置中的模板
  --repository-url value      指定 git 仓库 URL。如果未指定，使用配置中的 'repository_url'
  --output value, -o value    更改日志的输出路径和文件名。如果未指定，输出到标准输出
  --next-tag value            将未发布的提交视为指定的标签（实验性）
  --silent                    禁用标准输出（默认：false）
  --no-color                  禁用彩色输出（默认：false）[$NO_COLOR]
  --no-emoji                  禁用表情符号输出（默认：false）[$NO_EMOJI]
  --no-case                   禁用大小写敏感过滤器（默认：false）
  --tag-filter-pattern value  标签过滤的正则表达式。如果指定，只会选择匹配的标签
  --jira-url value            Jira URL [$JIRA_URL]
  --jira-username value       Jira 用户名 [$JIRA_USERNAME]
  --jira-token value          Jira 令牌 [$JIRA_TOKEN]
  --sort value                指定如何排序标签；目前支持按"日期"或"语义化版本"排序（默认：日期）
  --help, -h                  显示帮助（默认：false）
  --version, -v               打印版本（默认：false）

示例：

  $ git-chglog

    如果未指定 <标签查询>，则对应所有标签。
    这是最简单的示例。

  $ git-chglog 1.0.0..2.0.0

    上述命令用于生成包含 1.0.0 到 2.0.0 之间提交的 CHANGELOG。

  $ git-chglog 1.0.0

    上述命令用于生成仅包含 1.0.0 提交的 CHANGELOG。

  $ git-chglog $(git describe --tags $(git rev-list --tags --max-count=1))

    上述命令用于生成包含最新标签中提交的 CHANGELOG。

  $ git-chglog --output CHANGELOG.md

    上述命令将输出到 CHANGELOG.md 而不是标准输出。

  $ git-chglog --config custom/dir/config.yml

    上述命令使用放置在 ".chglog/config.yml" 以外位置的配置文件。

  $ git-chglog --path path/to/my/component --output CHANGELOG.component.md

    按 git 中的特定路径或文件过滤提交，并输出到组件特定的更改日志。

标签查询

您可以使用 <标签查询> 指定在生成 CHANGELOG 时包含哪些提交。

下表显示了查询模式、摘要和查询示例。

查询	描述	示例
<旧>..<新>	包含在 <新> 标签到 <旧> 标签之间的提交。	$ git-chglog 1.0.0..2.0.0
<名称>..	从 <名称> 到最新标签的提交。	$ git-chglog 1.0.0..
..<名称>	从最早的标签到 <名称> 的提交。	$ git-chglog ..2.0.0
<名称>	包含在 <名称> 中的提交。	$ git-chglog 1.0.0

配置

git-chglog 配置是一个 yaml 文件。默认位置是 .chglog/config.yml。

以下是您可以在 git-chglog 中使用的完整列表。

bin: git
style: ""
template: CHANGELOG.tpl.md
info:
  title: CHANGELOG
  repository_url: https://github.com/git-chglog/git-chglog

options:
  tag_filter_pattern: '^v'
  sort: "date"

  commits:
    filters:
      Type:
        - feat
    sort_by: Scope

  commit_groups:
    group_by: Type
    sort_by: Title
    title_order:
      - feat
    title_maps:
      feat: Features

  header:
    pattern: "<regexp>"
    pattern_maps:
      - PropName

  issues:
    prefix:
      - #

  refs:
    actions:
      - Closes
      - Fixes

merges: pattern: "^Merge branch '(\w+)'$" pattern_maps: - Source

reverts: pattern: "^Revert "([\s\S]*)"$" pattern_maps: - Header

notes: keywords: - BREAKING CHANGE

### `bin`

Git 执行命令。

| 是否必需 | 类型   | 默认值 | 描述 |
|:--------|:-------|:------|:----|
| 否      | String | `"git"` | -  |

### `style`

CHANGELOG 样式。自动链接问题和通知、合并等初始值设置会自动完成。

| 是否必需 | 类型   | 默认值  | 描述                                                   |
|:--------|:-------|:-------|:------------------------------------------------------|
| 否      | String | `"none"` | 应为 `"github"` `"gitlab"` `"bitbucket"` 或 `"none"` |

### `template`

模板文件路径。从设置文件指定相对路径。也可以使用绝对路径。

| 是否必需 | 类型   | 默认值              | 描述 |
|:--------|:-------|:-------------------|:----|
| 否      | String | `"CHANGELOG.tpl.md"` | -  |

### `info`

CHANGELOG 的元数据。根据样式的不同，有时会在处理中使用，所以建议指定。

| 键               | 是否必需 | 类型   | 默认值        | 描述              |
|:-----------------|:--------|:-------|:-------------|:-----------------|
| `title`          | 否      | String | `"CHANGELOG"` | CHANGELOG 的标题 |
| `repository_url` | 否      | String | 无            | git 仓库的 URL   |

### `options`

用于处理提交的选项。

#### `options.sort`

关于获取和排序提交的选项。

| 是否必需 | 类型   | 默认值  | 描述                                                           |
|:--------|:-------|:-------|:--------------------------------------------------------------|
| 否      | String | `"date"` | 定义在生成的变更日志中如何排序标签。值：`"date"`, `"semver"` |

#### `options.commits`

关于获取和排序提交的选项。

| 键        | 是否必需 | 类型        | 默认值    | 描述                                                                  |
|:----------|:--------|:------------|:---------|:---------------------------------------------------------------------|
| `filters` | 否      | Map in List | 无        | 使用 `Commit` 属性和值进行过滤。指定空值时不进行过滤                    |
| `sort_by` | 否      | String      | `"Scope"` | 用于排序 `Commit` 的属性名。参见 [Commit]                              |

#### `options.commit_groups`

提交组的选项。

| 键            | 是否必需 | 类型        | 默认值    | 描述                                                                         |
|:--------------|:--------|:------------|:---------|:----------------------------------------------------------------------------|
| `group_by`    | 否      | String      | `"Type"` | 将 `Commit` 分组到 `CommitGroup` 的属性名。参见 [CommitGroup][doc-commit]    |
| `sort_by`     | 否      | String      | `"Title"` | 用于排序 `CommitGroup` 的属性名。参见 [CommitGroup][doc-commit-group]        |
| `title_order` | 否      | List        | 无        | 用于排序 `CommitGroup` 的预定义标题顺序。仅当 `sort_by` 为 `Custom` 时使用    |
| `title_maps`  | 否      | Map in List | 无        | `CommitGroup` 标题转换的映射                                                 |

#### `options.header`

此选项用于解析提交头。

| 键             | 是否必需 | 类型   | 默认值 | 描述                                                                      |
|:---------------|:--------|:-------|:------|:-------------------------------------------------------------------------|
| `pattern`      | 是      | String | 无     | 用于解析提交头的正则表达式                                                 |
| `pattern_maps` | 是      | List   | 无     | 将 `HeaderPattern` 结果映射到 `Commit` 属性的规则。参见 [Commit][doc-commit] |

#### `options.issues`

此选项用于检测问题。

| 键       | 是否必需 | 类型 | 默认值 | 描述                                  |
|:---------|:--------|:----|:------|:-------------------------------------|
| `prefix` | 否      | List | 无     | 用于问题的前缀（例如 `#`、`#gh-`）    |

#### `options.refs`

此选项用于解析引用。

| 键        | 是否必需 | 类型 | 默认值 | 描述                                         |
|:----------|:--------|:----|:------|:--------------------------------------------|
| `actions` | 否      | List | 无     | `Ref.Action` 的单词列表。参见 [Ref][doc-ref] |

#### `options.merges`

用于检测和解析合并提交的选项。

| 键             | 是否必需 | 类型   | 默认值 | 描述                               |
|:---------------|:--------|:-------|:------|:----------------------------------|
| `pattern`      | 否      | String | 无     | 类似于 `options.header.pattern`    |
| `pattern_maps` | 否      | List   | 无     | 类似于 `options.header.pattern_maps` |

#### `options.reverts`

用于检测和解析还原提交的选项。

| 键             | 是否必需 | 类型   | 默认值 | 描述                               |
|:---------------|:--------|:-------|:------|:----------------------------------|
| `pattern`      | 否      | String | 无     | 类似于 `options.header.pattern`    |
| `pattern_maps` | 否      | List   | 无     | 类似于 `options.header.pattern_maps` |

#### `options.notes`

用于检测提交正文中包含的注释的选项。

| 键         | 是否必需 | 类型 | 默认值 | 描述                                                                                |
|:-----------|:--------|:----|:------|:-----------------------------------------------------------------------------------|
| `keywords` | 否      | List | 无     | 用于查找 `Note` 的关键字列表。分号是分隔符，格式为 `<keyword>:`（例如 `BREAKING CHANGE`） |

## 模板

`git-chglog` 模板使用 `text/template` 包和 [Sprig] 提供的增强模板函数。关于基本用法，请参考以下内容：

- [text/template](https://golang.org/pkg/text/template/)
- [Sprig]

我们实现了以下自定义模板函数。这些函数覆盖了 [Sprig] 提供的函数。
| 名称         | 签名                                         | 描述                                                                     |
| :----------- | :-------------------------------------------- | :------------------------------------------------------------------------ |
| `contains`   | `func(s, substr string) bool`                 | 使用 `strings.Contains` 检查 `substr` 是否在 `s` 中                          |
| `datetime`   | `func(layout string, input time.Time) string` | 根据布局生成格式化的日期字符串                                                  |
| `hasPrefix`  | `func(s, prefix string) bool`                 | 使用 `strings.HasPrefix` 测试字符串 `s` 是否以 `prefix` 开头                   |
| `hasSuffix`  | `func(s, suffix string) bool`                 | 使用 `strings.HasPrefix` 测试字符串 `s` 是否以 `suffix` 结尾                   |
| `indent`     | `func(s string, n int) string`                | 将 `s` 的所有行缩进 `n` 个空格                                                |
| `replace`    | `func(s, old, new string, n int) string`      | 使用 `strings.Replace` 在字符串 `s` 中将 `old` 替换为 `new`，替换 `n` 次        |
| `upperFirst` | `func(s string) string`                       | 将字符串的第一个字符转为大写                                                    |

如果您对准备好的模板不满意，请尝试自定义一个。

---

以下是基本模板：

**示例：**

```markdown
{{ if .Versions -}}
<a name="unreleased"></a>
## [未发布]

{{ if .Unreleased.CommitGroups -}}
{{ range .Unreleased.CommitGroups -}}
### {{ .Title }}
{{ range .Commits -}}
- {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}
{{ end }}
{{ end -}}
{{ end -}}
{{ end -}}

{{ range .Versions }}
<a name="{{ .Tag.Name }}"></a>
## {{ if .Tag.Previous }}[{{ .Tag.Name }}]{{ else }}{{ .Tag.Name }}{{ end }} - {{ datetime "2006-01-02" .Tag.Date }}
{{ range .CommitGroups -}}
### {{ .Title }}
{{ range .Commits -}}
- {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}
{{ end }}
{{ end -}}

{{- if .RevertCommits -}}
### 回滚
{{ range .RevertCommits -}}
- {{ .Revert.Header }}
{{ end }}
{{ end -}}

{{- if .MergeCommits -}}
### 拉取请求
{{ range .MergeCommits -}}
- {{ .Header }}
{{ end }}
{{ end -}}

{{- if .NoteGroups -}}
{{ range .NoteGroups -}}
### {{ .Title }}
{{ range .Notes }}
{{ .Body }}
{{ end }}
{{ end -}}
{{ end -}}
{{ end -}}

{{- if .Versions }}
[未发布]: {{ .Info.RepositoryURL }}/compare/{{ $latest := index .Versions 0 }}{{ $latest.Tag.Name }}...HEAD
{{ range .Versions -}}
{{ if .Tag.Previous -}}
[{{ .Tag.Name }}]: {{ $.Info.RepositoryURL }}/compare/{{ .Tag.Previous.Name }}...{{ .Tag.Name }}
{{ end -}}
{{ end -}}
{{ end -}}

有关可用变量，请参阅 godoc RenderData 文档。

支持的样式

名称	状态	特性
GitHub	:white_check_mark:	自动链接提及。自动链接到引用。
GitLab	:white_check_mark:	自动链接提及。自动链接到引用。
Bitbucket	:white_check_mark:	自动链接提及。自动链接到引用。

:memo: 即使对于尚未支持的样式，也可以制作普通的 CHANGELOG。

Jira 集成

Jira 是一款流行的项目管理工具。当项目使用 Jira 跟踪功能开发和错误修复时，可能还希望根据存储在 Jira 中的信息生成变更日志。通过在 git 提交头中嵌入 Jira 故事 ID，git-chglog 工具可以自动从 Jira 获取故事的数据，然后可以使用这些数据来渲染模板。

按照以下步骤添加 Jira 集成：

1. 在配置文件中更改头部解析模式以识别 Jira 问题 ID

其中 Jira 问题与 Jira 故事相同。

以下是一个示例模式：

header:
  pattern: "^(?:(\\w*)|(?:\\[(.*)\\])?)\\:\\s(.*)$"
  pattern_maps:
    - Type
    - JiraIssueID
    - Subject

此示例模式可以匹配两种形式的提交头：

• feat: 某功能的新特性
• [JIRA-ID]: 某事

2. 在配置文件中添加 Jira 配置

以下是一个示例：

jira:
  info:
    username: u
    token: p
    url: https://jira.com
  issue:
    type_maps:
      Task: fix
      Story: feat
    description_pattern: "<changelog>(.*)</changelog>"

在这里，您需要定义 Jira URL、访问用户名和令牌（密码）。如果您不想在配置文件中写入 Jira 访问凭据，可以使用环境变量定义它们：JIRA_URL、JIRA_USERNAME 和 JIRA_TOKEN。

您还需要定义问题类型映射。在上面的示例中，Jira 问题类型 Task 将映射到 fix，Story 将映射到 feat。

由于 Jira 故事的描述可能很长，您可能不想将整个描述包含在变更日志中。在这种情况下，您可以像上面那样定义 description_pattern，这样只有被 <changelog> ... </changelog> 包围的内容才会被包含。

3. 更新模板以显示 Jira 数据

在模板中，如果提交包含 Jira 问题 ID，则可以显示 Jira 数据。例如：

{{ range .CommitGroups -}}
### {{ .Title }}
{{ range .Commits -}}
- {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}
{{ if .JiraIssue }} {{ .JiraIssue.Description }}
{{ end }}
{{ end }}
{{ end -}}

在 Commit 中，可以在模板中使用以下 Jira 数据：

• .JiraIssue.Summary - Jira故事的摘要
• .JiraIssue.Description - Jira故事的描述
• .JiraIssue.Type - Jira故事的原始类型，.Type将是映射后的类型
• .JiraIssue.Labels - 字符串列表，每个都是一个Jira标签

常见问题

<details> <summary>为什么默认不输出文件？</summary> 这不是为了完全自动生成CHANGELOG文件，而只是为了辅助生成。

理想情况下，应该在提交中描述CHANGELOG中包含的所有内容。但实际上很难做到完美。

有时候你需要编辑生成的输出以写出一个优秀的CHANGELOG。

通过在标准输出上显示，可以更容易地修改内容。

</details> <details> <summary>我可以在创建标签之前提交CHANGELOG的更改吗？</summary>

可以，可以通过使用--next-tag标志来解决。

例如，假设你想将项目升级到2.0.0。 你可以按如下方式创建包含2.0.0的CHANGELOG。

git-chglog --next-tag 2.0.0 -o CHANGELOG.md
git commit -am "release 2.0.0"
git tag 2.0.0

需要注意的是，在实际用git创建标签之前，使用--next-tag传递下一个版本 :+1:

这在许多情况下是项目操作所必需的步骤。

</details> <details> <summary>我可以基于特定标签生成CHANGELOG吗？</summary>

可以，可以通过使用--tag-filter-pattern标志来解决。

例如，以下命令将只包含以"v"开头的标签：

git-chglog --tag-filter-pattern '^v'

</details>

待办事项

• Windows支持
• 更多样式（GitHub、GitLab、Bitbucket :tada:）
• 配置文件的片段化（提高可重用性）
• 更多测试测试测试...（和示例）

致谢

git-chglog的灵感来自conventional-changelog。感谢！

贡献

我们一直欢迎您的贡献 :clap:

开发

1. 使用Golang版本>= 1.19
2. Fork (https://github.com/git-chglog/git-chglog) :tada:
3. 创建一个功能分支 :coffee:
4. 运行测试套件，使用$ make test命令并确认通过 :zap:
5. 运行代码检查，使用$ make lint命令并确认通过 :broom:
   • 项目使用golangci-lint
6. 提交您的更改 :memo:
7. 将您的本地更改与master分支进行变基 :bulb:
8. 创建新的Pull Request :love_letter:

欢迎在issues中提出bug、功能请求和评论。

发布流程

Makefile中有一个release目标，它包装了发布新版本的步骤。

注意：运行命令时传递VERSION变量，以正确设置发布的标签版本。

$ VERSION=vX.Y.Z make release
# 示例：
$ VERSION=v0.11.3 make release

一旦tag被推送，goreleaser github action将处理剩余的工作。

反馈

我希望使git-chglog成为一个更好的工具。 目标是能够在各种项目中使用。

因此，您的反馈非常有用。 我很高兴在Issues和PR中听到您的意见 :heart:

更新日志

查看CHANGELOG.md

相关项目

• git-chglog/artwork - git-chglog的资源。

许可证

MIT © tsuyoshiwada