使用git管理更改日志的好方法？

时间：2010-08-19 15:43:52

标签： git github changelog

我一直在使用Git一段时间了，我最近开始用它来标记我的版本，以便我可以更轻松地跟踪更改并能够看到每个客户端运行的版本（不幸的是代码目前要求每个客户端都有自己的PHP站点副本;我正在改变它，但它很慢。）

无论如何，我们开始建立一些动力，我认为能够向人们展示自上次发布以来发生了哪些变化真的很好。问题是，我没有维护更改日志，因为我不知道如何去做。在这个特定时间，我可以浏览日志并手动创建一个日志，但这会非常快。

我尝试使用谷歌搜索“git changelog”和“git manage changelog”，但我没有找到任何真正谈论代码更改工作流程以及与更改日志一致的内容。我们目前正在关注Rein Henrichs' development workflow，我会喜欢与之相关的内容。

我是否缺少一种标准方法，或者这是一个每个人都做自己的事情的方法？

非常感谢您的意见/答案！

12 个答案:

答案 0 :(得分：156)

这是大约3 - 4年前，但为了未来的搜索者，现在可以生成华丽的日志：

git log --oneline --decorate

或者，如果你想让它更漂亮（用终端的颜色）：

git log --oneline --decorate --color

将输出管道输出到ChangeLog是我目前在所有项目中使用的，它简直太棒了。

答案 1 :(得分：55)

你可以使用一些git log来帮助你：

git log --pretty=%s                 # only print the subject

如果你很好地命名你的分支，那么合并到master会显示为“Merged branch feature-foobar”之类的东西，你可以通过仅显示该消息来缩短事物，而不是所有你合并的小提交，哪个一起形成功能：

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

你可以用你自己的脚本来增强它，这可以做一些事情，比如去除“Merged branch”位，规范化格式等等。当然，你必须自己编写它。

然后，您可以为每个版本创建一个更新日志的新部分：

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

并在您的版本发布中提交。

如果您的问题是那些提交主题与您想要放入更改日志中的内容不同，那么您几乎有两个选择：手动完成所有操作（并尝试更频繁地跟上它而不是在发布时播放追赶，或修复您的提交消息样式。一个选项，如果主题不打算为你做，将在你的提交消息的正文中添加诸如“更改：添加功能foobar”之类的行，以便稍后你可以执行类似git log --pretty=%B | grep ^change:的操作只抓取那些超重要的信息。

我不完全确定git能帮助您创建更改日志的程度。也许我误解了“管理”的含义？

答案 2 :(得分：50)

免责声明：我是gitchangelog的作者，我将在下面发言。

TL; DR：您可能想要检查生成上一个的gitchangelog's own changelog或ascii output。

如果您想从git历史记录中生成更改日志，您可能需要考虑：

  • 输出格式。 （纯自定义ASCII，Debian更改日志类型，Markdow，ReST ...）
  • 一些提交过滤（您可能不希望在更改日志中看到所有错字或内容更改）
  • 一些提交文本争论，然后才会包含在更改日志中。 （确保将消息规范化为首字母大写或最后一个点，但也可以删除摘要中的一些特殊标记）
  • 是您的 git history compatible ？大多数工具并不总是如此容易地支持合并，标记。这取决于你如何管理你的历史。

Optionaly你可能想要一些分类（新的东西，变化，错误修正）......

考虑到这一切，我创建并使用了gitchangelog。它意味着利用 git commit message convention 来实现之前的所有目标。

创建一个好的更改日志（使用或不使用gitchangelog）必须具有提交消息约定。

提交邮件约定

以下是考虑添加提交消息可能有用的建议。

您可能希望将提交大致分成大部分：

  • 意图（例如：new，fix，change ...）
  • 按对象（例如：doc，packaging，code ...）
  • 受众（例如：dev，测试人员，用户......）

此外，您可能想要标记一些提交：

  • as＆＃34; minor＆＃34;承诺不应该超出您的更改日志（整容更改，评论中的小错误......）
  • as＆＃34; refactor＆＃34;如果你真的没有任何有意义的功能变化。因此，这不应该也是最终用户显示的更改日志的一部分，但如果您有开发人员更改日志，则可能会有一些兴趣。
  • 您也可以使用＆＃34; api＆＃34;标记API更改或新API内容......
  • ...等...

尝试尽可能多地定位用户（功能）来编写提交消息。

示例

这是标准git log --oneline，用于说明如何存储这些信息:: 

* 5a39f73 fix: encoding issues with non-ascii chars.
* 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} ... ]

要查看实际输出结果，您可以查看gitchangelog

的PyPI页面的结尾

要查看我的提交消息约定的完整文档，您可以看到参考文件gitchangelog.rc.reference

如何从此

生成精美的更改日志

然后，制作完整的更改日志非常容易。您可以非常快速地创建自己的脚本，或使用gitchangelog。

gitchangelog将生成完整的更改日志（将分区支持设为New，Fix ...），并且可以合理地配置为您自己的提交约定。它支持任何类型的输出，这要归功于Mustache，Mako templating的模板，并且有一个用raw python编写的默认遗留引擎;所有当前的3个引擎都有如何使用它们的示例，并且可以输出更改日志，如gitchangelog的PyPI页面上显示的那样。

我确定您知道还有很多其他git log到changelog工具。

答案 3 :(得分：24)

更重要的是CHANGELOG。 如果有人喜欢，请告诉我。

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

答案 4 :(得分：22)

gitlog-to-changelog脚本可以生成GNU风格的ChangeLog。

如gitlog-to-changelog --help所示，您可以使用选项ChangeLog选择用于生成--since文件的提交：

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

或在--之后传递其他参数，这些参数将传递给git-log（由gitlog-to-changelog内部调用）：

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

此规则在发布时用于使用最新的尚未记录的提交消息更新ChangeLog。文件.last-cl-gen包含ChangeLog中记录的最新提交的SHA1标识符，并存储在Git存储库中。 ChangeLog也会记录在存储库中，以便可以在不更改提交消息的情况下对其进行编辑（例如更正拼写错误）。

答案 5 :(得分：17)

由于每个版本创建一个标记是最佳做法，因此您可能希望对每个版本的更改日志进行分区。在这种情况下，此命令可以帮助您：

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

答案 6 :(得分：12)

对于 GitHub 项目，它可能很有用： github-changelog-generator

它从标签已关闭的问题和合并的拉取请求生成更改日志。

此 CHANGELOG.md 是由此脚本生成的。

示例：

  

更新日志

     

1.2.5（2015-01-15）

     

Full Changelog

     

已实施增强功能：

     
      
  • 使用里程碑指定修复了哪个版本的错误#22
    •   
     

修正了错误：

     
      
  • 尝试为没有标记#32
    • 的repo生成日志时出错   
     

合并拉取请求：

     
      

  • PrettyPrint类包含使用小写的“pp”#43（schwing）

    •   

  • 通过命令行选项支持enterprise github #42（glenlovett）

    •   

答案 7 :(得分：10)

我也为此建立了一个库。它完全可以使用Mustache模板进行配置。那可以：

我也做了：

关于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}}
"

或者詹金斯：

enter image description here

答案 8 :(得分：3)

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

是我喜欢用的。它获取自上一个标记以来的所有提交。 cut摆脱了提交哈希。如果您在提交邮件的开头使用票号，则会将其与sort分组。如果您使用fix，typo等

为某些提交添加前缀，排序也会有所帮助

答案 9 :(得分：2)

根据bithavoc，它会在last tag之前列出HEAD。但我希望列出2个标签之间的日志。

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

列出2个标签之间的日志。

// 2 or 3 dots between 2 tags
git log FROM_TAG...TO_TAG

例如，它会列出从v1.0.0到v1.0.1的日志。

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

答案 10 :(得分：1)

对于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
}

有了这个：

  • 我定期提交更改以备份和重新定义它们，然后再对ChangeLog进行最终编辑
  • 然后运行：gnuc

现在我的剪贴板包含以下内容：

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

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

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

它并不完美（例如文件应该与其ChangeLog路径相关，所以python/py-symtab.c没有gdb/，因为我将编辑gdb/ChangeLog），但这是一个很好的起点。< / p>

更高级的脚本：

我不得不同意Tromey：在ChangeLog中复制git提交数据是没用的。

如果您要制作更改日志，请将其作为正常情况的摘要，可能与http://keepachangelog.com/

中指定的相同

答案 11 :(得分：1)

我让CI服务器将以下内容传递到名为CHANGELOG的文件中，每个新版本都在release-filename中设置日期：

>git log --graph --all --date=relative --pretty=format:"%x09 %ad %d %s (%aN)"
相关问题
最新问题