[Git Note] - 統一團隊的 Git Commit 格式吧！不要再讓 Commit 亂糟糟

發表於 更新於 分類於 ， ， 文章字數： 3.2k 所需閱讀時間 ≈ 3 分鐘

Introduction & 前言

Git

這是一篇教學如何美化 git commit 及客製化檢查程式碼還有檢查 git commit 內容的文章。

Summary & 摘要

這篇文章將會透過 Husky 及 Commitizen 格式化 git Commit 佐 Commitlint 檢查 git Commit 是否符合格式

Commitizen 的安裝及使用流程

Commitizen

  1. 安裝 Commitizen

    1
    2
    3
    4
    5
    $npm install commitizen

    // 或

    $yarn add commitizen

  2. 設定 Commitizen

    在 package.json 加上下面的設定

    1
    2
    3
    4
    5
    6
    7
    8
    // package.json
    {
      "config": {
        "commitizen": {
          "path": "cz-conventional-changelog"
        }
      }
    }

    (如果沒設定，之後輸入 git cz 會一樣以預設的 git commit 執行)

    如果有報錯找不到 cz-conventional-changelog 請輸入 npm install cz-conventional-changelog 或 yarn add cz-conventional-changelog 。

  3. 輸入 git cz 就能出現預設的問答

    git cz

    全部輸入完可以在輸入 git log 查看剛剛建立的 commit

Commitlint 的安裝及使用流程

如果需要定義 commit 的規範及格式，可以透過使用 Commitlint 來客製化需要規範的 commit 條件，例如敘述不可以小於五個字等等；基本上有使用 git cz 的話都大致能符合基本格式，除非提交者直接使用 git commit，並且輸入了不符合規範的格式。

如果不安裝使用 Commitlint，只有使用 Commitizen 將會讓這個統一規範的功能形同虛設，建議還是連同 Commitlint 一起安裝。

Commitlint GitHub

  1. 安裝 commitlint-cli 及 config-conventional

    1
    2
    3
    4
    5
    $npm install --save-dev @commitlint/{config-conventional,cli}

    // 或

    $yarn add --save-dev @commitlint/{config-conventional,cli}

  2. 產生 commitlint.config.js 並寫入設定

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

    更多規範可參考 commitlint 的 Document → Config

  3. 使用 commitlint

    1
    2
    3
    $ echo "add commitlint first" | npx commitlint
    > ✖   subject may not be empty [subject-empty]
    > ✖   type may not be empty [type-empty]

    使用 Commitlint 檢查 git commit

    如果 commit 不符合規範就會跳出錯誤，規範可參考 Conventional Commits

  4. 試試 echo "fix(package.json): add commitlint first" | npx commitlint 就不會報錯了

這邊建議繼續往下看，如果已經裝了 Commitizen 及 Commitlint，當然不能少了 Pre-commit 的檢查，請一併安裝 Husky 吧！

Husky 的安裝及使用流程

Husky Logo

Husky 聽起來很可愛，就像一隻可靠忠心的狗狗。

這隻狗狗可以讓開發者在不同的 git hook 執行不同的動作，例如建立 commit(pre-commit) 前執行 commit message 的檢查，或者 ESLint 的檢查。

  1. 安裝 Husky

    1
    2
    3
    4
    5
    $npx husky-init && npm install

    或

    $npx husky-init && yarn

  2. 如果有使用 commitlint 的話可以搭配下面指令

    1
    $npx husky add .husky/commit-msg 'npx --no-install commitlint --edit $1'

    這個指令會產生一支檔案 .husky/commit-msg，這個指令可以在 commit(pre-commit) 前執行檢查 commit message 有無符合 conventional commit 的規範。

    使用 create-react-app 記得把 .husky/pre-commit 裡面的 npm test 改為 npm test -- --watchAll=false ，不然輸入 git commit 後會卡在下圖(因為 create-react-app 預設是執行 watch mode)：

    Test 的錯誤

    修改後，成功的話會出現下圖(如果有寫 Test 的話才會跑出綠色或紅色 Icon)：

    Test 成功

  3. 這時候輸入 git commit，接著在 commit 隨意輸入 fix，接著送出：

    輸入隨意的 commit message

在這邊會在建立 commit message 的時候自動使用 commitlint 去檢查格式是否正確，錯誤的話就會如下圖：

Commit 格式錯誤

*如果沒有裝 commitlint 的話也只會跑 test 而已，並不會去檢查你的 commit message。*

延伸應用

更新日誌

Conventional Changelog Github

如果對於 git 需要更多紀錄可以使用 conventional-changelog 及 standard version，前者是紀錄所有 commit 的詳細記錄，後者則是可以產生版號紀錄，這些紀錄皆會記錄在 CHANGELOG.md。

Coding Style Check

如果需要使用 commit 前檢查 ESLint 的一些排版，可以安裝 ESLint 搭上 Husky。

Lint Staged GitHub

  1. 安裝 lint-staged

    1
    2
    3
    4
    5
    $ npm install husky lint-staged

    // 或

    $ yarn add husky lint-staged

    如果已經裝了 husky 就不用再裝一次了，輸入 npm install lint-staged 即可

  2. 根目錄創建 .huskyrc.json 然後輸入

    1
    2
    3
    4
    5
    {
      "hooks": {
        "pre-commit": "lint-staged"
      }
    }

  3. 根目錄創建 .lintstagedrc.json 然後輸入

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    {
      "*.+(js|jsx)": [
        "eslint --fix",
        "git add"
      ],
      "*.+(json|css|md)": [
        "prettier --write",
        "git add"
      ]
    }

    這樣符合規範通過檢查的檔案就會被 git add，如果不符合就不會。

Conclusion & 結論

前份工作因為常常只有一個前端開發一個專案，所以分支很簡單，主分支、開發分支…不會有很多額外分支。因為最近工作上碰到多人開發，而且需要發 PR 及定期開 UAT、Prod 的分支，所以大家的 Git Commit 都亂成一團，剛好想起之前有研究過 Husky，這次就一起整理成一份筆記。

主要還是透過 Commitlint 去檢查我們定義好的 Git Commit 格式是否正確，然後透過 Commitizen 去快速的產生符合規範格式，最後透過 Husky 在推出 commit 之前先行進行格式檢查。

如果有興趣的話也可以搭配延伸應用，一起檢查 ESLint 是否有符合規範，整套下來相信整個團隊都整齊一致，但最重要的還是要符合團隊的開發特性，還是那句話，沒有最厲害最好的程式碼及工具，只有最符合當下情況的語言及工具。

參考網站