Git Commit Message 规范

今天来说说团队开发中,对于 Git commit message 规范问题。

社区上有各种 Commit message 的规范,本文介绍 Angular 规范,目前使用较广,比较合理和系统化,并且有配套的工具。

1. 规范 Commit Msg 的作用

1) 提供更多的历史信息,方便快速浏览

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

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

2) 可以过滤某些 commit ,便于快速查找信息

例如,下面的命令过滤仅显示本次发布新增加的功能。

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

3) 可以直接从 commit 生成 Change Log

Change Log 是发布新版本时,用来说明与上一版本差异的文档。

2. Angular 规范的 Commit Msg 语法

每一次提交,Commit message 都包括 3 个部分: Header, BodyFooter

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

其中,Header 是必需的, Body 和 Footer 可以省略。

Commit Msg 的任何一行都不得超过 100 个字符。这样是为了在 GitHub 以及各种 Git 工具中更容易阅读。

2.1. Message Header

Header 部分只有一行,它包含对更改的简单描述,其中包括 「类型」( type )、「可选范围」( scope ) 和 「主题」( subject )。

//Message Header Demo

fix($compile): couple of unit tests for IE9

style($location): add couple of missing semi colons

feat($compile): simplify isolate scope bindings

2.1.1. 类型 type

type 用于说明 commit 的类别,只允许使用一下 7 个标示。

feat:新功能(feature)

fix:修补bug

docs:文档(documentation)

style: 格式(不影响代码运行的变动)

refactor:重构(即不是新增功能,也不是修改bug的代码变动)

test:增加测试

chore:构建过程或辅助工具的变动

2.1.2. 影响范围 scope

「范围」可以是指定提交更改位置的任何内容。例如 location 、browser 、 $compile 、 SrootScope 、 ngHref 、 ngClick 、 ngView 等。

如果没有合适的「范围」,可以用 *

2.1.3 主题 subject

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

* 使用祈使句,并且以第一人称现在时。

* 首字母不要大写

* 结尾 不要 加句号(dot)

2.2. Message 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) 使用第一人称现在时。

2) 应该说明代码变动的动机,以及与以前行为的对比。

2.3. Footer

2.3.1. 重大更改 Breaking Changes

所有的「重大更改」必须在 Footer 作为「重大更改块」被提及到,它应该以 BREAKING CHANGE: 开头,后面跟着一个空格或者两个空行。然后,Commit Msg 的其余部分是对更改,理由和迁移说明的描述。

REAKING CHANGE:


    isolate scope bindings definition has changed and
    the inject option for the directive controller injection was removed.
    
    To migrate the code follow the example below:
    
    Before:
    
    scope: {
      myAttr: 'attribute',
      myBind: 'bind',
      myExpression: 'expression',
      myEval: 'evaluate',
      myAccessor: 'accessor'
    }
    
    After:
    
    scope: {
      myAttr: '@',
      myBind: '@',
      myExpression: '&',
      // myEval - usually not useful, but in cases where the expression is assignable, you can use '='
      myAccessor: '=' // in directive's template change myAccessor() to myAccessor
    }
    
    The removed `inject` wasn't generaly useful for directives so there should be no code using it.

2.3.2. 关闭 Issue (Referencing Issues)

如果当前 commit 针对某个 issue ,那么可以在 Footer 部分关闭这个 issue 。Closes 关键字为前缀。

Closes #123

也可以一次关闭多个 issue 。

Closes #123, #243, #545

2.4. 还原 (Revert)

如果当前的 commit 是还原到之前的 commit,那么当前 Commit msg Header 要以 revert: 开头,并且后面紧跟着还原 Commit 的 Header 。这时 Body 里面要以 This reverts commit <hash> 固定式,其中 <hash> 是 commit 的 SHA 标示符。

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

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

参考文献

Angular 规范: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit

阮一峰 博客: http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 158,736评论 4 362
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 67,167评论 1 291
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 108,442评论 0 243
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 43,902评论 0 204
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 52,302评论 3 287
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 40,573评论 1 216
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 31,847评论 2 312
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 30,562评论 0 197
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 34,260评论 1 241
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 30,531评论 2 245
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 32,021评论 1 258
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 28,367评论 2 253
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 33,016评论 3 235
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 26,068评论 0 8
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,827评论 0 194
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 35,610评论 2 274
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 35,514评论 2 269

推荐阅读更多精彩内容