花有重开时,人无再少年

0%

如何生成 Markdown 格式的 Git 日志

如今 Markdown 格式的文档在技术领域无处不在,尤其是在开源工具和技术文档方面,例如 GitHub、GitLab 等等基于 Git 的版本控制平台。一般情况下,Git 使用 git-log 来生成两次提交之间的变更日志信息。有时我们希望将此次版本发布的更新日志抽取出来,以 markdown 格式作为发布的版本的变更日志内容。

git-log

以下是我们利用 git-log 命令格式化出来一段 eliu/kt-connect-rbac 仓库的变更日志:

1
2
3
4
5
6
7
8
$ git log --no-merges --format="%h %ad %an %s" --date=short HEAD
da7815d 2020-09-29 eliu imp: make 6443 port by default if not specified
73ef9aa 2020-05-05 eliu imp: update README
6bd8192 2020-05-05 eliu fix: correct default value
003bb7e 2020-05-05 eliu fix: execute init_config inside prerequisite
9f1326c 2020-05-04 eliu imp: refactor all scripts into one kt-rbac.sh
c34a405 2020-03-20 Liu Hongyu Create LICENSE
b9e3175 2020-03-20 eliu first commit

其中 --no-merges 表示通过 Merge 请求所产生的提交可忽略,--date=short 表示以简短的日期格式输出(yyyy-mm-dd),--format="xxxxx" 表示日志输出的格式模板,具体可输入 git log --help 了解详细的占位符含义。

加工成 MD 格式

我们将 --format 选项稍加调整即可变成符合 markdown 格式的表格内容,例如:

1
# --format="| %h | %ad | %an | %s |"

再辅以表格的标题内容即可变成完整的 MD 格式的变更日志内容:

sample

形成通用脚本

根据以上的思路,我这里写了一个可以在终端快速生成 Markdown 格式的变更日志的脚本,支持将一组相似的仓库批量生成变更日志,例如:

1
2
3
./changelog-v1.0.3.sh --prefix kt --until HEAD
[INFO] CHANGELOG will be written to file CHANGELOG-HEAD.md
[INFO] Appending change logs for kt-connect-rbac ...

此时在脚本所在的目录中生成了一个 Markdown 格式的日志文件 CHANGELOG-HEAD.md, 使用 Markdown 编辑器打开该文件即可得到上面截图的效果。脚本提供了 --prefix, --since--until 选项可以使用,有兴趣的同学可以下载下来尝试一下。

脚本下载地址:changelog-v1.0.3.sh