使用git管理变更日志的好方法?

这是在2015年,但为了未来的搜索者,现在可以生成华丽的日志:

git log --oneline --decorate

git log --oneline --decorate --color

输出到的管道 是我目前在所有项目中使用的,这简直令人惊叹。

你可能想检查一下 gitchangelog's own changelog ASCII output 产生了前一个。

如果要从Git历史生成changelog,可能需要考虑:

• 输出格式 Debian 更改日志类型, Markdown REST
• 一些 提交筛选
• 提交文本争用 在包含在变更日志中之前。(确保消息规范化为第一个字母大写或最后一个点,但也可能删除摘要中的一些特殊标记。)
• Git历史兼容

或者,您可能需要一些分类(新事物、更改、错误修复等)。

考虑到这些,我创造并使用 gitchangelog Git提交消息约定

有一个提交消息约定对于创建一个好的变更日志是必需的(无论是否使用 gitchangelog

提交消息约定

您可能希望将提交大致分为几个大部分:

• 按意图(例如:新建、修复、更改等)
• 按受众(例如:开发人员、测试人员、用户等)

• 作为“次要”提交,不应输出到您的变更日志(外观变更、注释中的小错误等)
• 如果没有任何显著的特性更改,就称为“重构”。因此,这不应该也是向最终用户显示的变更日志的一部分,但是如果您有一个开发人员变更日志,它可能会引起一些兴趣。
• 你也可以用“API”来标记API更改或新的API内容。。。
• …等等。。。

尽可能多地以用户(功能)为目标来编写提交消息。

例子

这是标准 git log --oneline

* 5a39f73 fix: encoding issues with non-ASCII characters.
* a60d77a new: pkg: added ``.travis.yml`` for automated tests.
* 57129ba new: much greater performance on big repository by issuing only one shell command for all the commits. (fixes #7)
* 6b4b267 chg: dev: refactored out the formatting characters from Git.
* 197b069 new: dev: reverse ``natural`` order to get reverse chronological order by default. !refactor
* 6b891bc new: add UTF-8 encoding declaration !minor

如果你注意到了,我选择的格式是:

{new|chg|fix}: [{dev|pkg}:] COMMIT_MESSAGE [!{minor|refactor} ... ]

要查看实际的输出结果,可以查看 PyPI gitchangelog公司 .

要查看我的提交消息约定的完整文档,可以查看引用文件 gitchangelog.rc.reference

如何从中生成精美的变更日志

然后,很容易就可以创建一个完整的变更日志。你可以很快地编写自己的脚本,或者使用 gitchangelog公司 .

gitchangelog公司 将生成一个完整的变更日志(以分段支持为基础) New Fix …)并且可以根据您自己的提交约定进行合理配置。由于通过模板化,它支持任何类型的输出 Mustache Mako templating gitchangelog公司

我相信你知道还有很多 git log changelog 还有工具。

_{免责声明: gitchangelog公司}

你可以尝尝 git log 要帮助您:

git log --pretty=%s                 # Only prints the subject

git log --pretty=%s --first-parent  # Only follow the first parent of merges

你可以用你自己的脚本来扩充它,比如去掉“合并的分支”位,规范格式,等等。当然,在某个时候你必须自己写。

git log [opts] vX.X.X..vX.X.Y | helper-script > changelogs/X.X.Y

并在你的版本中提交。

如果主题不打算为您这样做,一个选择是在提交消息的主体中放置“change:added feature foobar”这样的行,以便以后您可以执行以下操作 git log --pretty=%B | grep ^change: 只获取那些超级重要的信息。

更切题的更改日志:

git log --since=1/11/2011 --until=28/11/2011 --no-merges --format=%B

这个 gitlog-to-changelog 脚本可以方便地生成GNU样式 ChangeLog .

如所示 gitlog-to-changelog --help ,您可以选择用于生成 变更日志 --since :

gitlog-to-changelog --since=2008-01-01 > ChangeLog

或者在 -- git-log (由内部调用) ):

gitlog-to-changelog -- -n 5 foo > last-5-commits-to-branch-foo

例如,我在顶层使用以下规则 Makefile.am 我的一个项目:

.PHONY: update-ChangeLog
update-ChangeLog:
    if test -d $(srcdir)/.git; then                         \
       $(srcdir)/build-aux/gitlog-to-changelog              \
          --format='%s%n%n%b%n' --no-cluster                \
          --strip-tab --strip-cherry-pick                   \
          -- $$(cat $(srcdir)/.last-cl-gen)..               \
        >ChangeLog.tmp                                      \
      && git rev-list -n 1 HEAD >.last-cl-gen.tmp           \
      && (echo; cat $(srcdir)/ChangeLog) >>ChangeLog.tmp    \
      && mv -f ChangeLog.tmp $(srcdir)/ChangeLog            \
      && mv -f .last-cl-gen.tmp $(srcdir)/.last-cl-gen      \
      && rm -f ChangeLog.tmp;                               \
    fi

EXTRA_DIST += .last-cl-gen

此规则在发布时用于更新 最新尚未录制的提交消息。文件 .last-cl-gen 包含中记录的最新提交的SHA-1标识符 变更日志 并存储在Git存储库中。 变更日志 也会记录在存储库中,这样就可以编辑它(例如更正打字错误),而不必更改提交消息。

因为每个版本创建一个标记是最佳实践,所以您可能需要按照每个版本对变更日志进行分区。在这种情况下,此命令可以帮助您:

git log YOUR_LAST_VERSION_TAG..HEAD --no-merges --format=%B

Mustache 模板。可以:

• CHANGELOG.md .
• MediaWiki
• 或者只是打印成标准输出

我还做了:

• A Gradle plugin
• Maven plugin
• Jenkins plugin
• A Bitbucket Server plugin
• command line tool

有关GitHub的更多详细信息: https://github.com/tomasbjerre/git-changelog-lib

从命令行:

npx git-changelog-command-line -std -tec "
# Changelog

Changelog for {{ownerName}} {{repoName}}.

{{#tags}}
## {{name}}
 {{#issues}}
  {{#hasIssue}}
   {{#hasLink}}
### {{name}} [{{issue}}]({{link}}) {{title}} {{#hasIssueType}} *{{issueType}}* {{/hasIssueType}} {{#hasLabels}} {{#labels}} *{{.}}* {{/labels}} {{/hasLabels}}
   {{/hasLink}}
   {{^hasLink}}
### {{name}} {{issue}} {{title}} {{#hasIssueType}} *{{issueType}}* {{/hasIssueType}} {{#hasLabels}} {{#labels}} *{{.}}* {{/labels}} {{/hasLabels}}
   {{/hasLink}}
  {{/hasIssue}}
  {{^hasIssue}}
### {{name}}
  {{/hasIssue}}

  {{#commits}}
**{{{messageTitle}}}**

{{#messageBodyItems}}
 * {{.}}
{{/messageBodyItems}}

[{{hash}}](https://github.com/{{ownerName}}/{{repoName}}/commit/{{hash}}) {{authorName}} *{{commitTime}}*

  {{/commits}}

 {{/issues}}
{{/tags}}
"

或者在詹金斯:

git log --oneline --no-merges `git describe --abbrev=0 --tags`..HEAD | cut -c 9- | sort

是我喜欢用的。它获取自上一个标记以来的所有提交。 cut 除去提交散列。如果在提交消息的开头使用票证号,则它们将按 sort . 如果在某些提交前加上 fix , typo 等等。

我让他走了 CI 服务器将以下内容通过管道传输到名为 CHANGELOG

git log --graph --all --date=relative --pretty=format:"%x09 %ad %d %s (%aN)"

基于 bithavoc ,下面列出 最后一个标记 直到 HEAD . 但我希望列出两个标签之间的日志。

// Two or three dots between `YOUR_LAST_VERSION_TAG` and `HEAD`
git log YOUR_LAST_VERSION_TAG..HEAD --no-merges --format=%B

列出两个标记之间的日志:

// Two or three dots between two tags
git log FROM_TAG...TO_TAG

例如,这将列出 v1.0.0 v1.0.1 :

git log v1.0.0...v1.0.1 --oneline --decorate

GNU样式更改日志

为了一个 GNU style changelog

gnuc() {
  {
    printf "$(date "+%Y-%m-%d")  John Doe  <john.doe@gmail.com>\n\n"
    git diff-tree --no-commit-id --name-only -r HEAD | sed 's/^/\t* /'
  } | tee /dev/tty | xsel -b
}

有了这个:

• 然后运行: gnuc

现在我的剪贴板包含如下内容:

2015-07-24  John Doe  <john.doe@gmail.com>

        * gdb/python/py-linetable.c (): .
        * gdb/python/py-symtab.c (): .

然后我使用剪贴板作为更新变更日志的起点。

它不是完美的(例如,文件应该相对于它们的ChangeLog路径,所以 python/py-symtab.c 没有 gdb/ 因为我会编辑 gdb/ChangeLog ),但这是一个很好的起点。

更高级的脚本:

• git-gnu-changelog
• 合同通用条款 contrib/mklog
• gcc/contrib/mklog

如果你要做一个变更日志,那就做一个好的 总结 正在发生的事情,可能是在 Keep a Changelog