526互联

从 Git 提交历史生成 Release Note

发布时间 2023-03-22 21:12:53作者: 1bite

发布软件时写 Release Note 算是常规操作，但每次从头手打也有点累，可以考虑从 Git 的提交历史中自动生成。

Git 提交信息一般是三段式结构，段落之间使用空行隔开：

<subject>
// 空行
<body>
// 空行
<trailers>

subject 和 body 自不必多说，trailers 中一般是一条条键-值对构成的信息，键和值由冒号 : 分隔。比如 Git 的 Commiter: 就可以视为一条 trailer，Gerrit 代码审查通过后，也会在 Git 提交消息中添加 Reviewed-by: 和 Tested-by: 之类的 trailer。

现假设提交信息中的 trailers 包含 Type 和 Issue 字段，分别表示类别（NewFeature, BugFix 之类）和 BUG 编号（GitHub 上的 issue 编号或者内部系统的 BUG 编号）：

Fixed a crash

- blahblah
- blahblahblah

Type: BugFix
Issue: issue-120

就可以结合 git log 和 awk 生成 Rlease Note:

git log --format='%(trailers:key=Type,valueonly,separator=%x20)%x1c%s [%(trailers:key=Issue,valueonly,separator=,)]' $FROM..HEAD | awk -F "\034" '
    {
        gsub(/\[\]$/, "", $2);
        if (length($1) == 0) $1="MISC";
        if (!($1 in item_count)) item_count[$1]=0;
        items[$1, item_count[$1]]=$2;
        item_count[$1]++;
    }
    END {
        for (k in item_count) {
            print k;
            k2=k;
            gsub(/./, "-", k2);
            print k2
            for (i=0; i<item_count[k]; i++) print "* "items[k, i];
            print ""
        }
    }'

输出：

BugFix
------
* Fixed a typo
* Fixed a crash [issue-120]

NewFeature
----------
* Added some magic

选择使用 awk 处理 git log 的输出是因为 linux 跟 macOS 都带这个软件，不需要额外安装依赖。
Git 2.22.0 及以上版本才支持按键值筛选 trailers。

在 Windows 系统上，可能没有办法直接运行 .sh 文件。但是如果安装了 Windows 版本的 Git，则会带一个 Git Bash（更重要的是，也带了 awk），这样就可以在 Git Bash 中运行 .sh 文件，也可以创建一个 .cmd 文件包装一下：

@ECHO off
SETLOCAL

CALL :FIND-PATH GITEXE_PATH git.exe
IF "%GITEXE_PATH%"=="" (
    ECHO git.exe is not found on your system
    EXIT /B 2
)

CALL :GET-DIR-NAME GITEXE_DIR "%GITEXE_PATH%"
CALL :GET-DIR-NAME GITEXE_DIR "%GITEXE_DIR:~0,-1%"

@"%GITEXE_DIR%bin\bash.exe" release-note.sh %*

:FIND-PATH
SET "%~1=%~f$PATH:2"
EXIT /B

:GET-DIR-NAME
SET "%~1=%~dp2"
EXIT /B