GitChangelog詳解：簡單生成美觀的CHANGELOG.md文件

一、GitChangelog簡介

GitChangelog是一種簡單易用的Python工具，它可以將Git提交歷史轉換為Markdown格式，生成CHANGELOG.md文件，方便用戶查看項目的更新歷史。GitChangelog可以自定義哪些提交類型應該在CHANGELOG.md文件中顯示，可以按時間或根據標識符來生成文件，並且可以使用Jinja2模板引擎自定義輸出格式。

以下是一個簡單的例子，展示如何使用GitChangelog來生成一個CHANGELOG.md文件：

$ gitchangelog -o CHANGELOG.md --no-summary --strip-brackets 

這個命令將生成一個CHANGELOG.md文件，其中每個提交都會按照時間順序列出。 --no-summary 選項會省略生成的文件中的摘要。

--strip-brackets 選項還會去掉提交信息中的方括號。

二、GitChangelog的常用選項

-o, --output FILENAME

此選項將指定輸出文件的名稱。

例如，在終端運行以下命令將生成名為“CHANGELOG.md”的文件：

$ gitchangelog -o CHANGELOG.md

--configfile FILENAME

此選項允許您指定一個GitChangelog配置文件。

例如，您可以將每個提交類型的配置存儲在名為“changelog.cfg”的文件中，並在終端運行以下命令來指定它：

$ gitchangelog --configfile changelog.cfg

--repository URL

此選項將允許您指定Git存儲庫的URL。

例如，以下是在您的終端中指定存儲庫的URL的示例：

$ gitchangelog --repository https://github.com/example/repo.git

--since TAG

此選項將從指定的Git標記開始創建CHANGELOG.md文件。

例如，以下是以“v1.0.0”標記為起點創建CHANGELOG.md文件的示例：

$ gitchangelog --since v1.0.0

--until TAG

此選項將在指定的Git標記之前創建CHANGELOG.md文件。

例如，以下是在“v2.0.0”標記之前創建CHANGELOG.md文件的示例：

$ gitchangelog --until v2.0.0

三、GitChangelog的用法示例

1、使用自定義配置文件

您可以使用自定義配置文件來指定哪些提交類型應在CHANGELOG.md文件中顯示，以及它們的順序。

以下是一個簡單的示例，展示如何使用自定義配置文件來生成CHANGELOG.md文件：

$ gitchangelog --configfile changelog.cfg -o CHANGELOG.md

GitChangelog將在“changelog.cfg”文件中查找提交類型和它們的順序，並使用這些信息來生成CHANGELOG.md文件。

2、使用Jinja2模板引擎自定義輸出格式

您可以使用Jinja2模板引擎來自定義CHANGELOG.md文件的輸出格式。

以下是一個示例，展示如何在GitChangelog中使用Jinja2模板引擎：

$ gitchangelog -t mytemplate.j2 -o CHANGELOG.md

在此示例中，GitChangelog將使用名為“mytemplate.j2”的Jinja2模板來生成CHANGELOG.md文件。

3、根據Git標記生成CHANGELOG.md文件

您可以使用Git標記來生成CHANGELOG.md文件。 這對於以版本為單位創建CHANGELOG.md文件非常有用。

以下是一個示例，展示如何根據Git標記生成CHANGELOG.md文件：

$ gitchangelog --tags -o CHANGELOG.md

在此示例中，GitChangelog將根據所有Git標記生成CHANGELOG.md文件。

4、快速生成CHANGELOG.md文件

如果您想要快速生成一個簡單的CHANGELOG.md文件，可以使用以下命令：

$ gitchangelog -o CHANGELOG.md --no-merges --strip-brackets --no-verbose

此命令將使用以下選項來快速生成CHANGELOG.md文件：

• --no-merges選項將排除合併提交。
• --strip-brackets選項會去掉提交信息中的方括號。
• --no-verbose選項將僅顯示提交消息，而不是細節。

您可以根據需要自定義這些選項。

四、結論

在本文中，我們了解了GitChangelog的基本用法，介紹了GitChangelog的常用選項，並提供了幾個示例。希望這篇文章可以幫助您更好地管理您的Git提交歷史並生成漂亮的CHANGELOG.md文件。