git commit message 和 Change log

Commit message 的格式

每次提交，Commit message 都包括三个部分：Header，Body 和 Footer。

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

其中，Header 是必需的，Body 和 Footer 可以省略。 不管是哪一个部分，任何一行都不得超过 72 个字符（或 100 个字符）。这是为了避免自动换行影响美观。

Header 部分只有一行，包括三个字段：type（必需）、scope（可选）和subject（必需）。

type用于说明commit的类别，只允许使用下面 7 个标识。

  1. feat 新功能（feature）
  2. fix 修补 bug
  3. docs 文档（documentation）
  4. style 格式（不影响代码运行的变动）
  5. ref 重构（即不是新增功能，也不是修改 bug 的代码变动）
  6. test 增加测试
  7. chore 构建过程或辅助工具的变动

如果type为feat和fix，则该commit将肯定出现在Change log之中。其他情况（docs、chore、style、refactor、test）由你决定，要不要放入Change log，建议是不要。

  1. 以动词开头，使用第一人称现在时，比如change，而不是 changed或 changes

  2. 第一个字母小写

  3. 结尾不加句号（.）

Body

Body 部分是对本次 commit 的详细描述，可以分成多行。下面是一个范例。

More detailed explanatory text, if necessary.  Wrap it to
about 72 characters or so.

Further paragraphs come after blank lines.

- Bullet points are okay, too
- Use a hanging indent

有两个注意点。

  1. 使用第一人称现在时，比如使用change而不是 changed或 changes
  2. 应该说明代码变动的动机，以及与以前行为的对比

Footer 部分只用于两种情况。

BREAKING CHANGE: isolate scope bindings definition has changed.

    To migrate the code follow the example below:

    Before:

    scope: {
      myAttr: 'attribute',
    }

    After:

    scope: {
      myAttr: '@',
    }

    The removed `inject` wasn't generaly useful for directives so there should be no code using it.

如果当前commit针对某个issue，那么可以在Footer部分关闭这个issue。

Closes #234

也可以一次关闭多个 issue 。

Closes #123, #245, #992

Revert

还有一种特殊情况，如果当前commit用于撤销以前的commit，则必须以revert:开头，后面跟着被撤销Commit的Header。

revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Body部分的格式是固定的，必须写成This reverts commit <hash>，其中的hash是被撤销commit的SHA标识符。

如果当前commit与被撤销的commit，在同一个发布（release）里面，那么它们都不会出现在Change log里面。如果两者在不同的发布，那么当前commit，会出现在 Change log的Reverts小标题下面。

Commitizen

Commitizen 是一个撰写合格Commit message的工具。

安装命令如下。(遇到缺少 package.json 文件的解决办法在文章最后)

$ npm install -g commitizen

$ npm install -g cz-conventional-changelog

echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

以后，凡是用到git commit命令，一律改为使用git cz。这时，就会出现选项，用来生成符合格式的Commit message。

生成 Change log

如果你的所有Commit都符合Angular格式，那么发布新版本时，Change log就可以用脚本自动生成（例 1:karma/CHANGELOG.md, 例 2:btford/grunt-conventional-changelog）。

生成的文档包括以下三个部分。

每个部分都会罗列相关的commit，并且有指向这些commit的链接。当然，生成的文档允许手动修改，所以发布前，你还可以添加其他内容。

conventional-changelog-cli 就是生成Change log的工具，运行下面的命令即可。

$ npm install -g conventional-changelog-cli
$ cd my-project

打印到屏幕

$ conventional-changelog -p angular -i CHANGELOG.md -w

输出到文件

$ conventional-changelog -p angular -i CHANGELOG.md -s

上面命令不会覆盖以前的Change log，只会在CHANGELOG.md的头部加上自从上次发布以来的变动。

如果你想生成所有发布的Change log，要改为运行下面的命令。

$ conventional-changelog -p angular -i CHANGELOG.md -s -r 0

为了方便使用，可以将其写入package.json的scripts字段。

{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -w -r 0"
  }
}

以后，直接运行下面的命令即可。

$ npm run changelog

缺少 package.json 文件

因为commitizen工具是基于 Node.js 的，而我们 iOS 项目工程目录下是没有package.json文件，所以会报错：

Error: ENOENT: no such file or directory, open '/Users/***/package.json

关于这个问题，可以参考这个commitizen的 issue：Usage in non-node projects?，对于非 Node 的项目，我们可先在我们项目中添加一个空的package.json文件，然后再输入命令：

$ npm init --yes

先初始化配置 package.json 文件，然后再输入命令：

$ commitizen init cz-conventional-changelog --save --save-exact

参考链接