前言

记录一下git日志的规范化写法，采用Angular 规范。

提交格式

每次提交，Commit message 都包括三个部分：header，body 和 footer。

其中，header 是必需的，body 和 footer 可以省略。

不管是哪一个部分，任何一行都不得超过72个字符（或100个字符）。这是为了避免自动换行影响美观。

1
2
3
4
5
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

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

参数说明如下：

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

以下表格来自阿里技术

标识 含义
feat 新功能（feature）
fix/to 修复 bug，可以是 QA 发现的 BUG，也可以是研发自己发现的 BUG。 fix：产生 diff 并自动修复此问题。适合于一次提交直接修复问题 to：只产生 diff 不自动修复此问题。适合于多次提交。最终修复问题提交时使用 fix
docs 文档（documentation）
style 格式（不影响代码运行的变动）
refactor 重构（即不是新增功能，也不是修改 bug 的代码变动）。
perf 优化相关，比如提升性能、体验。
test 增加测试。
chore 构建过程或辅助工具的变动。
revert 回滚到上一个版本。
merge 代码合并。
sync 同步主线或分支的 Bug。

scope用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。

例如在Angular，可以是$location, $browser, $compile, $rootScope, ngHref, ngClick, ngView等。

如果你的修改影响了不止一个scope，你可以使用*代替。

subject是 commit 目的的简短描述，不超过50个字符。

其他注意事项：

  • 以动词开头，使用第一人称现在时，比如change，而不是changed或changes
  • 第一个字母小写
  • 结尾不加句号（.）

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

1
2
3
4
5
6
7
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

有两个注意点:

  • 使用第一人称现在时，比如使用change而不是changed或changes。
  • 永远别忘了第2行是空行
  • 应该说明代码变动的动机，以及与以前行为的对比。

Footer 部分只用于以下两种情况：

不兼容变动

如果当前代码与上一个版本不兼容，则 Footer 部分以BREAKING CHANGE开头，后面是对变动的描述、以及变动理由和迁移方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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.

关闭 Issue

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

1
Closes #234

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

1
2
3
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小标题下面。

作用

提供更多的历史信息，方便快速浏览。

比如，下面的命令显示上次发布后的变动，每个commit占据一行。你只看行首，就知道某次 commit 的目的。

1
$ git log <last tag> HEAD --pretty=format:%s

可以过滤某些commit（比如文档改动），便于快速查找信息

1
$ git log <last release> HEAD --grep feature

使用

Commitizen

可以使用典型的git工作流程或通过使用CLI向导Commitizen来添加提交消息格式。

安装

1
npm install -g commitizen

然后，在项目目录里，运行下面的命令，使其支持 Angular 的 Commit message 格式。

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

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

validate-commit-msg

validate-commit-msg 用于检查项目的 Commit message 是否符合Angular规范。

该包提供了使用githooks来校验commit message的一些二进制文件。在这里，我推荐使用husky，只需要添加"commitmsg": "validate-commit-msg"到你的package.json中的nam scripts即可.

当然，你还可以通过定义配置文件.vcmrc来自定义校验格式。详细使用请见文档 validate-commit-msg

生成 Change log

如果你的所有 Commit 都符合 Angular 格式，那么发布新版本时， Change log 就可以用脚本自动生成。生成的文档包括以下三个部分：

  • New features
  • Bug fixes
  • Breaking changes.

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

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

1
2
3
$ npm install -g conventional-changelog
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -w

VScode

vscode 中 Git-commit-plugin 插件可以快速生成提交模板。

设置项

  • 展示 Emoji

    默认为 true。可在设置中修改

  • 提交类型

    增加其他的提交类型，需要在 json 中添加。

    1
    2
    3
    4
    5
    6
    JSON"GitCommitPlugin.CustomCommitType": [
      {
        "label": "customTypeName",
        "detail": "customTypeDetail"
      }
    ]

  • subject 最大长度

    subject 的最大长度限制，默认为 20。可在设置中修改。

表情

commit中可以使用表情符号

emoji emoji 代码 commit 说明
🎨 (调色板) :art: 改进代码结构 / 代码格式
⚡️ (闪电) 🐎 (赛马) :zap: :racehorse: 提升性能
🔥 (火焰) :fire: 移除代码或文件
🐛 (bug) :bug: 修复 bug
🚑 (急救车) :ambulance: 重要补丁
✨ (火花) :sparkles: 引入新功能
📝 (备忘录) :memo: 撰写文档
🚀 (火箭) :rocket: 部署功能
💄 (口红) :lipstick: 更新 UI 和样式文件
🎉 (庆祝) :tada: 初次提交
✅ (白色复选框) :white_check_mark: 更新测试
🔒 (锁) :lock: 修复安全问题
🍎 (苹果) :apple: 修复 macOS 下的问题
🐧 (企鹅) :penguin: 修复 Linux 下的问题
🏁 (旗帜) :checkered_flag: 修复 Windows 下的问题
🤖（机器人） :robot: 修复 Android 下的问题
🍏 (绿苹果) :green_apple: 修复 iOS 下的问题
🔖 (书签) :bookmark: 发行 / 版本标签
🚨 (警车灯) :rotating_light: 移除 linter 警告
🚧 (施工) :construction: 工作进行中
👷 (工人) :construction_worker: 添加 CI 构建系统
💚 (绿心) :green_heart: 修复 CI 构建问题
⬆️ (上升箭头) :arrow_up: 升级依赖
⬇️ (下降箭头) :arrow_down: 降级依赖
📌 (图钉) :pushpin: 将依赖项固定到特定版本
📈 (上升趋势图) :chart_with_upwards_trend: 添加分析或跟踪代码
♻️ （回收） :recycle: 重构代码
🐳 (鲸鱼) :whale: Docker 相关工作
🌐 (带子午线的地球仪) :globe_with_meridians: 国际化与本地化
➕ (加号) :heavy_plus_sign: 增加一个依赖
➖ (减号) :heavy_minus_sign: 减少一个依赖
🔧 (扳手) :wrench: 修改配置文件
🔨 (锤子) :hammer: 重大重构
✏️ (铅笔) :pencil2: 修复 typo
💩 (粑粑…) :hankey: 写了辣鸡代码需要优化
⏪ (倒带) :rewind: 恢复更改
🔀 (交叉向右的箭头) :twisted_rightwards_arrows: 合并分支
📦 (包裹) :package: 更新编译的文件或包
👽 (外星人) :alien: 由于外部 API 更改而更新代码
🚚 (货车) :truck: 移动或者重命名文件
📄 (正面朝上的页面) :page_facing_up: 增加或更新许可证书
💥 (爆炸) :boom: 引入突破性的变化
🍱 (铅笔) :bento: 增加或更新资源
👌 (OK 手势) :ok_hand: 由于代码审查更改而更新代码
♿️ (轮椅) :wheelchair: 改善无障碍交互
💡 (灯泡) :bulb: 给代码添加注释
🍻 (啤酒) :beers: 醉醺醺地写代码…
💬 (消息气泡) :speech_balloon: 更新文本文档
🗃 (卡片文件盒) :card_file_box: 执行与数据库相关的更改
🔊 (音量大) :loud_sound: 增加日志
🔇 (静音) :mute: 移除日志
👥 (轮廓中的半身像) :busts_in_silhouette: 增加贡献者
🚸 (孩童通行) :children_crossing: 优化用户体验、可用性
🏗 (建筑建造) :building_construction: 结构变动
📱 (iPhone) :iphone: 做响应式设计
🤡 (小丑脸) :clown_face: 嘲弄事物（直译，这个没明白）
🥚 (鸡蛋) :egg: 增加彩蛋
🙈 (看不见邪恶) :see_no_evil: 增加或更改 gitignore
📸 (照相机闪光灯) :camera_flash: 增加或更新截图
⚗️ (蒸馏器) :alembic: 尝试新东西
🔍 (放大镜) :mag: SEO 优化
☸️ (船的方向盘) :wheel_of_dharma: 关于 Kubernetes 的工作
🏷 (标签) :label: 增加类型（FLow、Typescript）

参考资料