引言
在日常的開發工作中,我們通常使用 git 來管理代碼,當我們對代碼進行某項改動後,都可以通過 git commit 來對代碼進行提交。
git 規定提交時必須要寫提交信息,作為改動說明,保存在 commit 歷史中,方便回溯。規範的 log 不僅有助於他人 review, 還可以有效的輸出 CHANGELOG,甚至對於項目的研發質量都有很大的提升。
但是在日常工作中,大多數同學對於 log 信息都是簡單寫寫,沒有很好的重視,這對於項目的管理和維護來說,無疑是不友好的。本篇文章主要是結合我自己的使用經驗來和大家分享一下 git commit 的一些規範,讓你的 log 不僅“好看”還“實用”。
為什麼要規範 git commit
一直在說要規範 commit 格式,那為什麼要這樣做呢?
讓我們先來看一個不太規範的 commit 記錄:
看完什麼感覺,寫的是啥啊(內心 OS),這種 commit 信息對於想要從中獲取有效信息的人來說無疑是一種致命的打擊。
那我們來看一個社區裡面比較流行的 Angular規範 的 commit 記錄:
看完是不是一目瞭然呢?
上圖中這種規範的 commit 信息首先提供了更多的歷史信息,方便快速瀏覽。其次,可以過濾某些 commit(比如文檔改動),便於快速查找信息。
既然說到了 Angular 團隊的規範 是目前社區比較流行的 commit 規範,那它具體是什麼呢?下面讓我們來具體深入瞭解下吧。
Angular 團隊的 commit 規範
它的 message 格式如下:
<code><type>(<scope>): <subject>// 空一行// 空一行<footer>/<subject>/<scope>/<type>/<code>
分別對應 Commit message 的三個部分: Header , Body 和 Footer 。
Header
Header 部分只有一行,包括三個字段: type (必需)、 scope (可選)和 subject (必需)。
- type : 用於說明 commit 的類型。一般有以下幾種:feat: 新增feature fix: 修復bug docs: 僅僅修改了文檔,如readme.md style: 僅僅是對格式進行修改,如逗號、縮進、空格等。不改變代碼邏輯。 refactor: 代碼重構,沒有新增功能或修復bug perf: 優化相關,如提升性能、用戶體驗等。 test: 測試用例,包括單元測試、集成測試。 chore: 改變構建流程、或者增加依賴庫、工具等。 revert: 版本回滾
- scope : 用於說明 commit 影響的範圍,比如: views, component, utils, test...
- subject : commit 目的的簡短描述
Body
對本次 commit 修改內容的具體描述, 可以分為多行。如下所示:
<code># body: 72-character wrapped. This should answer:# * Why was this change necessary?# * How does it address the problem?# * Are there any side effects?# initial commit/<code>
Footer
一些備註, 通常是 BREAKING CHANGE (當前代碼與上一個版本不兼容) 或修復的 bug(關閉 Issue) 的鏈接。
簡單介紹完上面的規範,我們下面來說一下 commit.template ,也就是 git 提交信息模板。
git 提交信息模板
如果你的團隊對提交信息有格式要求,可以在系統上創建一個文件,並配置 git 把它作為默認的模板,這樣可以更加容易地使提交信息遵循格式。
通過以下命令來配置提交信息模板:
<code>git config commit.template [模板文件名] //這個命令只能設置當前分支的提交模板git config — —global commit.template [模板文件名] //這個命令能設置全局的提交模板,注意global前面是兩槓/<code>
新建 .gitmessage.txt (模板文件) 內容可以如下:
<code># headr: <type>(<scope>): <subject># - type: feat, fix, docs, style, refactor, test, chore# - scope: can be empty# - subject: start with verb (such as 'change'), 50-character line## body: 72-character wrapped. This should answer:# * Why was this change necessary?# * How does it address the problem?# * Are there any side effects?## footer:# - Include a link to the issue.# - BREAKING CHANGE#/<subject>/<scope>/<type>/<code>
看完上面這些,你會不會像我一樣感覺配置下來挺麻煩的,配置一個適合自己和團隊使用的近乎完美的 commit 規範看來也不是一件容易的事情。不過社區也為我們提供了一些輔助工具來幫助進行提交,下面來簡單介紹一下這些工具。
commitizen(cz-cli)
commitizen 是一款可以交互式建立提交信息的工具。它幫助我們從 type 開始一步步建立提交信息,具體效果如圖所示:
- 首先通過上下鍵控制指向你想要的 type 類型,分別對應有上面提到的 feat 、 fix 、 docs 、 perf 等:
- 然後會讓你選擇本次提交影響到的文件:
- 後面會讓你分別寫一個簡短的和詳細的提交描述:
- 最後會讓你去判斷本次提交是否是 BREAKING CHANGE 或者有關聯已開啟的 issue :
看完上面的 commitizen 的整個流程,下面讓我們來看下如何來安裝。
- 全局環境下安裝:commitizen 根據不同的 adapter 配置 commit message。例如,要使用 Angular 的 commit message 格式,可以安裝 cz-conventional-changelog 。# 需要同時安裝commitizen和cz-conventional-changelog,後者是adapter $ npm install -g commitizen cz-conventional-changelog # 配置安裝的adapter $ echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc # 使用 $ git cz
- 本地項目安裝:# 安裝commitizen $ npm install --save-dev commitizen # 接下來安裝適配器 # for npm >= 5.2 $ npx commitizen init cz-conventional-changelog --save-dev --save-exact # for npm < 5.2 $ ./node_modules/.bin/commitizen init cz-conventional-changelog --save-dev --save-exact // package.json>
commitlint
commitlint 是一個提交驗證工具。原理是可以在實際的 git commit 提交到遠程倉庫之前使用 git 鉤子來驗證信息。提交不符合規則的信息將會被阻止提交到遠程倉庫。
先來看一下演示:
對於 Conventional Commits 規範,社區已經整理好了 @commitlint/config-conventional 包,我們只需要安裝並啟用它就可以了。
首先安裝 commitlint 以及 conventional 規範:
<code>npm install --save-dev @commitlint/cli @commitlint/config-conventional/<code>
接著在 package.json 中配置 commitlint 腳本:
<code>"commitlint": { "extends": [ "@commitlint/config-conventional" ] },/<code>
當然如果你想單獨對 commitlint 進行配置的話,需要建立校驗文件 commitlint.config.js ,不然會校驗失敗
為了可以在每次 commit 時執行 commitlint 來 檢查我們輸入的 message,我們還需要用到一個工具 —— husky 。
husky 是一個增強的 git hook 工具。可以在 git hook 的各個階段執行我們在 package.json 中配置好的 npm>
首先安裝 husky:
<code>npm install --save-dev husky/<code>
接著在 package.json 中配置 commitmsg 腳本:
<code>"husky": { "hooks": { "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" } },/<code>
到這裡, commitlint 就配置完成了~
gitmoji-cli
平時與朋友聊天時,我們一定會用到表情包,比如。表情包的出現讓我們與朋友之間的溝通變得更加有趣。如果能在 git 提交 commit 時用到表情包,豈不是使每次的 commit 能夠更加直觀,維護起來也更加方便。
gitmoji 就是可以實現這種功能的插件,先讓我們來感受一下
有沒有感覺很 cool~~
其實 gitmoji 的使用是很簡單的:
<code># 安裝npm i -g gitmoji-cli# 使用git commit -m ':bug: 問題fix'/<code>
我們來看一下官方的示例吧:
是不是躍躍欲試了呢?
gitmoji項目地址
gitmoji使用示例
看完本文,是不是感覺對於 git commit message 又有了新的認識呢?去在你的項目中運用這些吧,讓你的commit更加規範的同時,也不要忘了給你的log加上 emoji 哦!
最後附上一個之前項目針對git commit配置的 package.json ,作為參考:
<code>{ "name": "ts-axios", "version": "0.0.0", "description": "", "keywords": [], "main": "dist/ts-axios.umd.js", "module": "dist/ts-axios.es5.js", "typings": "dist/types/ts-axios.d.ts", "files": [ "dist" ], "author": "fengshuan <[email protected]>", "repository": { "type": "git", "url": "" }, "license": "MIT", "engines": { "node": ">=6.0.0" }, "scripts": { "dev": "node examples/server.js", "lint": "tslint --project tsconfig.json -t codeFrame 'src/**/*.ts' 'test/**/*.ts'", "prebuild": "rimraf dist", "build": "tsc --module commonjs && rollup -c rollup.config.ts && typedoc --out docs --target es6 --theme minimal --mode file src", "start": "rollup -c rollup.config.ts -w", "test": "jest --coverage", "test:watch": "jest --coverage --watch", "test:prod": "npm run lint && npm run test -- --no-cache", "deploy-docs": "ts-node tools/gh-pages-publish", "report-coverage": "cat ./coverage/lcov.info | coveralls", "commit": "git-cz", "semantic-release": "semantic-release", "semantic-release-prepare": "ts-node tools/semantic-release-prepare", "precommit": "lint-staged", "travis-deploy-once": "travis-deploy-once" }, "husky": { "hooks": { "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" } }, "lint-staged": { "{src,test}/**/*.ts": [ "prettier --write", "git add" ] }, "config": { "commitizen": { "path": "node_modules/cz-conventional-changelog" } }, "jest": { "transform": { ".(ts|tsx)": "ts-jest" }, "testEnvironment": "node", "testRegex": "(/__tests__/.*|\\\\.(test|spec))\\\\.(ts|tsx|js)$", "moduleFileExtensions": [ "ts", "tsx", "js" ], "coveragePathIgnorePatterns": [ "/node_modules/", "/test/" ], "coverageThreshold": { "global": { "branches": 90, "functions": 95, "lines": 95, "statements": 95 } }, "collectCoverageFrom": [ "src/*.{js,ts}" ] }, "prettier": { "semi": false, "singleQuote": true }, "commitlint": { "extends": [ "@commitlint/config-conventional" ] }, "devDependencies": { "@commitlint/cli": "^7.1.2", "@commitlint/config-conventional": "^7.1.2", "@types/jest": "^23.3.2", "@types/node": "^10.11.0", "body-parser": "^1.19.0", "colors": "^1.3.2", "commitizen": "^3.0.0", "coveralls": "^3.0.2", "cross-env": "^5.2.0", "cz-conventional-changelog": "^2.1.0", "express": "^4.17.1", "husky": "^1.0.1", "jest": "^23.6.0", "jest-config": "^23.6.0", "lint-staged": "^8.0.0", "lodash.camelcase": "^4.3.0", "prettier": "^1.14.3", "prompt": "^1.0.0", "replace-in-file": "^3.4.2", "rimraf": "^2.6.2", "rollup": "^0.67.0", "rollup-plugin-commonjs": "^9.1.8", "rollup-plugin-json": "^3.1.0", "rollup-plugin-node-resolve": "^3.4.0", "rollup-plugin-sourcemaps": "^0.4.2", "rollup-plugin-typescript2": "^0.18.0", "semantic-release": "^15.9.16", "shelljs": "^0.8.3", "travis-deploy-once": "^5.0.9", "ts-jest": "^23.10.2", "ts-loader": "^6.1.1", "ts-node": "^7.0.1", "tslint": "^5.11.0", "tslint-config-prettier": "^1.15.0", "tslint-config-standard": "^8.0.1", "tslint-loader": "^3.5.4", "typedoc": "^0.12.0", "typescript": "^3.0.3", "webpack": "^4.40.2", "webpack-dev-middleware": "^3.7.1", "webpack-hot-middleware": "^2.25.0" }}/<code>
閱讀更多 sandag 的文章