如何写好 Git commit messages
导语:任何软件项目都是一个协作项目,它至少需要2个开发人员参与,当原始的开发人员将项目开发几个星期或者几个月之后,项目步入正规。不过他们或者后续的开发人员仍然需要经常提交一些代码去修复bug或者实现新的feature。我们经常有这种感受:当一个项目时间过了很久之后,我们对于项目里面的文件和函数功能渐渐淡忘,重新去阅读熟悉这部分代码是很浪费时间并且恼人的一件事。但是这也没法完全避免,我们可以使用一些技巧尽可能减少重新熟悉代码的时间。commit messages可以满足需要,它也反映了一个开发人员是否是良好的协作者。
编写良好的Commit messages可以达到3个重要的目的:
- 加快review的流程
- 帮助我们编写良好的版本发布日志
- 让之后的维护者了解代码里出现特定变化和feature被添加的原因
先来看看一个比较好的例子,感受一下:
下面谈谈,如何让项目里面的Commit messages步入规范化,流程化。
Commit messages的基本语法
<type>: <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
Type表示提交类别,Subject表示标题行, Body表示主体描述内容。
Type的类别说明:
- feat: 添加新特性
- fix: 修复bug
- docs: 仅仅修改了文档
- style: 仅仅修改了空格、格式缩进、都好等等,不改变代码逻辑
- refactor: 代码重构,没有加新功能或者修复bug
- perf: 增加代码进行性能测试
- test: 增加测试用例
- chore: 改变构建流程、或者增加依赖库、工具等
Commit messages格式要求
# 标题行:50个字符以内,描述主要变更内容
#
# 主体内容:更详细的说明文本,建议72个字符以内。 需要描述的信息包括:
#
# * 为什么这个变更是必须的? 它可能是用来修复一个bug,增加一个feature,提升性能、可靠性、稳定性等等
# * 他如何解决这个问题? 具体描述解决问题的步骤
# * 是否存在副作用、风险?
#
# 如果需要的化可以添加一个链接到issue地址或者其它文档
这3个问题给代码的变更建立了良好的上下文,可以让其他的代码review人员或者项目成员直观的判断修改点是否正确。一条良好的commit message也可以让维护者知道这个patch是否适合发布到稳定的版本中去。
如果一个patch没有回答上面的这几个问题,那么它是无意义的。它会给review的人员造成负担,让他们花费大量时间去评审讨论这个patch的作用和意义。更糟糕的是,如果一个项目实施SCM纪律,则这个patch会被拒绝掉,然后开发人员需要花费时间重新编写一个新的patch。重新编写一个复杂的patch代价是巨大的,而把commit message写好只会花费几分钟。
Commit messages书写建议
- 尽可能多的提交,单个Commit messages包含的内容不要过多
- 标题行以Fix, Add, Change, Delete开始,采用命令式的模式。不要使用Fixed, Added, Changed等等
- 始终让第二行是空白,不写任何内容
- 主体内容注意换行,避免在gitk里面滚动条水平滑动
- 永远不在 git commit 上增加 -m 或 --message= 参数,提交的时候git commit即可。
- 如果你是vim用户,将下面这行代码加入到~/.vimrc。这会帮助你检查拼写和自动换行
autocmd Filetype gitcommit setlocal spell textwidth=72
使用Commitizen工具
Commitizen可以让你的commit message更加规范统一,适合项目团队使用,使用也很简单,使用npm安装后,提交代码的时候使用git cz去替代以前的git commit命令即可。
安装commitizen:
$ npm install -g commitizen
使用截图:
自动生成Change log
conventional-changelog是用来从git的元数据中生成 Change log文档的工具,只要你提交的格式满足它定义的标准,此处以angular标准为例子。使用它生成的Change log包含以下三个部分:
Bug Fixes Bug修复的信息
Features 增加的特性
BREAKING CHANGES 重大变更
可以参考它生成的文档CHANGELOG.md,使用如下:
$ npm install -g conventional-changelog-cli
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -s
这不会覆盖你之前的CHANGE.md文档内容,会在这个文件的最上面插入新生成的日志信息。
参考链接
- Git Commit Messages : 50/72 Formatting
- Distributed Git - Contributing to a Project
- thoughtbot
- Erlang otp
- Commit messages standard
- conventional-changelog-cli
开源信息
- 腾讯NOW直播前端工程化解决方案feflow正式开源啦~: https://github.com/cpselvis/feflow-cli
如何写好 Git commit messages的更多相关文章
- 如何写好git commit message
1.触发事件 我有这样一个版本库,里面包含两个学习用的练习项目:BookStore(以下简称BS)和PictureFriend(以下简称PF) 我在更改PF以后,未进行提交,同时又到BS中优化了一下文 ...
- git commit -m与-am的区别
前面的话 使用git commit -am是不是就可以完全不使用git add命令呢?不是 理论 要了解git commit -m与git commit -am的区别,首先要明白它们的定义 字面解释的 ...
- 从code review到Git commit log
最近在读一本技术类的书:朱赟——<跃迁:从技术到管理的硅谷路径>,其中聊了很多很有趣的观点,比如:技术管理.技术实践.硅谷文化.个人成长等. 读到关于硅谷人如何做code review这一 ...
- Git commit 信息标准和丢弃必须要的commit
/***************************************************************************** * Git commit 信息标准和丢弃必 ...
- 如何规范git commit提交
相信很多人使用SVN.Git等版本控制工具时候都会觉得每次提交都要写一个注释有什么用啊?好麻烦,所以我每次都是随便写个数字就提交了,但是慢慢的我就发现了,如果项目长期维护或者修改很久之前的项目,没有一 ...
- git commit guidelines
git-commit-guidelines AngularJS Development Setup Running Tests Coding Rules Commit Message Guidelin ...
- 写一个体验良好的git commit
一直在使用git也看过格式各样commit log , review 代码时最刺激的是看到这类 "." 应付差事,还有 "fix bug","fix& ...
- 我是怎么写 Git Commit message 的?
目录 作用 用的什么规范? type scope subject body footer 参考文章 用的什么辅助工具? 作用 编写格式化的 commit message 能够大大提高代码的维护效率. ...
- 规范git commit提交记录和版本发布记录
在开发过程中我们一般都会用到git管理代码,在git commit提交代码时我们一般对git commit message随便写点简单的描述,可是随着项目参与人数的增多,发现提交的commit记录越来 ...
随机推荐
- 打包程序时的证书问题(上传APP就出现Missing iOS Distribution signing indetity for)
现象: 解决办法: 1.删除本地钥匙串中的这个文件,注意“系统”中的同名文件也必须删除 2.进入http://www.apple.com/certificateauthority/ 下载新的(WWDR ...
- 代码中动态改变布局属性RelativeLayout.LayoutParams.addRule()
我们知道,在 RelativeLayout 布局中有很多特殊的属性,通常在载入布局之前,在相关的xml文件中进行静态设置即可. 但是,在有些情况下,我们需要动态设置布局的属性,在不同的条件下设置不同的 ...
- 【Xilinx-VDMA模块学习】-00-开始
最近在做XILINX图像相关的逻辑,需要用到VDMA模块,最后算是把这个模块摸得比较透了. 先在这里记一下,之后有空了总结一下.包括VDMA在Vivado中的GUI配置和软件驱动的详细理解.
- 【转】sql语句的优化分析
开门见山,问题所在 sql语句性能达不到你的要求,执行效率让你忍无可忍,一般会时下面几种情况. 网速不给力,不稳定. 服务器内存不够,或者SQL 被分配的内存不够. sql语句设计不合理 没有相应的索 ...
- 利用JS做到隐藏div和显示div
div的visibility可以控制div的显示和隐藏,但是隐藏后页面显示空白 style="visibility: none;" document.getElementById( ...
- Delphi在Vasta/win 7下通过UAC控制
在Windows编程时,为了兼容Win7与XP,许多需要底层权限的程序需要通过UAC验证,这是微软出的一个很恶心的东西……还不如Ubuntu那种Root机制呢……但是有困难我们就要克服-现在有一种方式 ...
- --@angularJS--指令与控制器之间的交互demo
1.index.html: <!DOCTYPE HTML><html ng-app="app"><head> <title>c ...
- magento1.x 运行在 php7 优惠券的问题
diff --git app/code/core/Mage/Sales/etc/config.xml index 5bb43d7..7db62ca 100644 --- app/code/core/M ...
- Java线程:同步
一 同步的概念 线程的同步是为了防止多个线程访问一个数据对象时,对数据造成的破坏. 例如:两个线程ThreadA.ThreadB都操作同一个对象Foo对象,并修改Foo对象上的数据. MyRunnab ...
- JSP 初始化参数
JSP 初始化参数: tomcat启动的时候就会执行那个函数: xml: <?xml version="1.0" encoding="UTF-8"?> ...