git commit message specification and constraint (Global Installation)

git commit message format

Every git commit code must write commit message (commit), used to describe the purpose of this submission, otherwise not allowed to commit.

 git commit -m "hello world"

The above code -mparameter is used to specify the commit message.

Written specification commit message there are many, this article describes the most widely used at present, more reasonable and systematic norm: Angular specification.

A, Commit message format

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

Wherein, Header is needed, Body and Footer may be omitted.

Header section is only one line includes three fields: type(required), scope(optional), subject(required)

type

type of categories for explaining a commit, allows the following identification 7.

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

scope

scopeCommit for explaining the influence of the range, such as the data layer, the control layer, layer view, etc., differ depending on the project.

subject

subjectA brief description of the purpose of commit, no more than 50 characters.

Precautions:

Beginning with a verb, first person now use, such as Change, not changed or changes
The first letter lowercase
End without a period (.)

1.2 Body () a second portion

Body part of this detailed description of the commit can be divided into multiple lines. (Line with \ n)

Footer part used in two cases only.

Incompatible changes

If the current code is not compatible with the previous version, the Footer section to BREAKING CHANGEbegin with, followed by a description of the changes, and changes in the grounds and migration methods.

Close Issue

If the current commit for a certain issue, you can turn off this issue in the Footer section.

  Closes #234

You can also close the issue once more.

  Closes #123, #245, #992

二、Commitizen

We know that the specification submitted, you need tools to generate and constraints. After passing through the help of tools commitizen cz-cli installation /, it will have a normative statement tips, help us form a standardized commit message.

Commitizen is a writing tool of qualified Commit message.

Global installation, the command is as follows:

  npm install -g commitizen cz-conventional-changelog

To see if the installation was successful

  npm ls -g -depth=0

The global mode, ~ / .czrc profile, as designated Adapter commitizen example: cz-conventional-changelog (a specification compliance team Angular preset).

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

After successful installation, the corresponding git project, who used git committhe command, should be used instead git cz. At this time, there will be options to generate properly formatted Commit message.

Third, check for compliance Commit message

Commitlint

commitlint we commit message for checking compliance with the filing specifications, if not, then simply refuse to submit.

Global Installation

  npm install -g @commitlint/cli @commitlint/config-conventional

Generate a configuration file

  echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

You can also submit message specification developed in commitlint.config.js

  "module.exports = {extends: ['@commitlint/config-conventional']}"

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      "feat", "fix", "docs", "style", "refactor", "test", "chore", "revert"
    ]],
    'subject-full-stop': [0, 'never'],
    'subject-case': [0, 'never']
  }
};

Above, we have completed the installation and delivery requirements of the development of commitlint. But the best way to test commit message is a combination of git hook, so the need to meet Husky.

Husky

husky inherits all the hooks under Git, when the trigger hook, husky can prevent illegal commit, push, and so on.

Creating package.json file
into git project execution

  npm init --yes

The project will generate a corresponding item of package.json

Into the project, installing husky

  npm install husky

After successful installation you need to configure package.json project:

  "husky": {
    "hooks": {
      "commit-msg": "commitlint -e $GIT_PARAMS"
    }
  }

We then normal operation git

  git add .
  git commit -m "test"

The above message does not meet the specifications submitted, it will be given as follows:

It played a role in verification.

Fourth, generate Change Log

If all of your Commit comply Angular format, when the new version is released, Change log can be automatically generated script

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

New features
Bug fixes
Breaking changes

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

conventional-changelog 就是生成 Change log 的工具。

安装changelog

  npm install -g conventional-changelog
  npm install -g conventional-changelog-cli

进入git项目目录下，执行命令：

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

以上命令中参数-p angular用来指定使用的 commit message 标准为angular，参数-i CHANGELOG.md表示生成的 changelog输出到 CHANGELOG.md 文件中。
命令执行完会在项目中生成CHANGELOG.md文件

注意：上面这条命令产生的 changelog 是基于上次 tag 版本(本地的tag版本)之后的变更（Feature、Fix、Breaking Changes等等）所产生的，如果你想生成之前所有 commit 信息产生的 changelog 则需要使用这条命令：

  conventional-changelog -p angular -i CHANGELOG.md -w -r 0

由于命令过长，可以在package.json中配置scripts

  
{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
  }
}

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

  npm run changelog

standard-version 也是生成 Change log 的工具。

正常情况下，版本发布流程如下：

git pull origin master
根据 pacakage.json 中的 version 更新版本号，更新 changelog
git add -A,然后git commit
git tag打版本操作
push版本tag和master分支到远程仓库

conventional-changelog工具需要在手动修改了pacakage.json版本号，生成了changelog之后，手动commit及打tag。但standard-version工具会自动完成2、3、4项的工作。如果再配合本地的shell脚本，则可以自动的完成一系列的版本发布工作。

安装(推荐全局安装)

  npm i -g standard-version

在package.json中配置：

  "scirpt": {
    ...,
    "release": "standard-version"
}

使用：

  npm run release

最终会在git项目中生成CHANGELOG.md文件

跟conventional-changelog生成的文件差不多。

更详细的用法：

--first-release, -f 第一次打版本

  standard-version -f

生成与package.json中版本号一致的tag。本地不能存在一样版本号的tag。

--release-as, -r 指定版本号

默认情况下，工具会自动根据主版本（major）,次版本（ minor） or 修订版（patch）规则生成版本号，例如如果你package.json 中的version 为 4.3.1, 那么执行后版本号则是：4.4.0。

standard-version -r minor

查看生成的tag:自动生成v4.4.0

查看提交记录：修改已经自动提交

最后提交本地代码与tag

  git push origin master
  git push origin --tags

会在github上看到提交记录与tag。

也可以固定版本：

  standard-version -r 5.0.0
  standard-version -r 5.0.0-test

会生成v5.0.0和5.0.0-test版本

--prerelease, -p 预发版本命名

用来生成预发版本, 如果当期的版本号是 4.4.0，例如

  standard-version -p
  standard-version -p alpha
  standard-version -p test

会生成v4.4.1-0、v4.4.1-alpha.0、v4.4.1-test.0。其中alpha、test代表预发布版本的名称。

--tag-prefix, -t 版本 tag 前缀

默认有一个前缀v,如果不想有任何前缀，直接用-t即可。
当前版本4.4.1

  standard-version -t "stable-"
  standard-version -t "test-"

生成：test-5.0.0、stable-5.1.0,其中 test是第一次作为前缀使用，所以会生成一个主版本。

综合使用：

  standard-version -t 'stable-' -r 6.1.0

生成 stable-6.1.0

--dry-run

  standard-version --dry-run

此命令会在允许你在后台查看将运行哪些步骤，不会修改package.json、changlog，也不会提交任何代码及生成tag。可以其他命令结合使用。

  standard-version -r 9.0.0 --dry-run

可用于查看该命令是否满足你的需求。

Lifecycle scripts 生命周期脚本

standard-version支持生命周期脚本。这些脚本允许你在发布期间去执行自己的补充命令。以下为生命周期的钩子，并按照文档顺序执行：

prerelease: executed before anything happens. If the prerelease script returns a non-zero exit code, versioning will be aborted, but it has no other effect on the process.
prebump/postbump: executed before and after the version is bumped. If the prebump script returns a version #, it will be used rather than the version calculated by standard-version.
prechangelog/postchangelog: executes before and after the CHANGELOG is generated.
precommit/postcommit: called before and after the commit step.
pretag/posttag: called before and after the tagging step.

在package.json中配置lifecycle scripts：

  {
  "standard-version": {
    "scripts": {
      "prebump": "echo 1.2.0"
    }
  }
}

执行standard-version会生成v1.2.0的版本。

跳过生命周期步骤(Skipping lifecycle steps)

You can skip any of the lifecycle steps (bump, changelog, commit, tag), by adding the following to your package.json:

  {
  "standard-version": {
    "skip": {
      "changelog": true
    }
  }
}