接續昨天的 git add 今天要繼續往下說的是 git commit，也就是把舞台區正式寫進儲存庫，讓儲存庫記憶住這次的變化內容的指令。對樂高的手冊編輯來說，git commit這指令，就相對於寫組裝手冊時，正式把一個步驟需要增加減少的樂高積木們，以及怎麼編排、怎麼組裝的方法，寫進手冊中，讓它真的形成一個步驟。

如同今天的標題所說的，編寫的組裝手冊是要讓人看的，所以，是不是所有的人都可以看懂讀懂，是一件需要特別在意的事情。對於 GIT 來說，透過git commit 儲存原始碼的變更之後，是不是能讓下一個使用這個儲存庫的人，順利的了解這個 commit 對應的原始碼新增修改範圍、目的、方法、影響範圍。

一個 commit message 可以怎麼表達呢？

一個 commit message 對於查看儲存庫的人來說，至少有兩個視角，第一個是查看 commit 列表的視角，第二個是查看單一個 commit的視角。對於使用儲存庫的人來說，通常是透過 commit 列表 找到想找的單一個 commit。而在一般 GIT 的工具上，在列表頁上，只會顯示每個 commit 的 message 內容的第一行，要再往下看更細部的內容，則必須選取該 commit 時查看才可以看到細部內容。因此利用這個特性，在撰寫 commit message 的時候，會有一些原則，以下就介紹兩個比較常見的原則。

How to Write a Git Commit Message 文章中提到的：

The seven rules of a great GIT commit message

1. Separate subject from body with a blank line

2. Limit the subject line to 50 characters

3. Capitalize the subject line

4. Do not end the subject line with a period

5. Use the imperative mood in the subject line

6. Wrap the body at 72 characters

7. Use the body to explain what and why vs. how

中文翻譯：

1. 標題與內容中間多一行空白

2. 標題限制 50 字元

3. 標題第一個字必須為大寫

4. 標題最後不要帶上句號

5. 標題內容可以使用強烈的語氣

6. 內容每 72 個字元斷行

7. 內容可以多解釋 what and why vs. how

Conventional Commits

A specification for adding human and machine readable meaning to commit messages.

在現行專案開發的歷程中，通常會搭配一些專案管理工具，如 JIRA、GitLab Issue Board、GitHub Issue、Redmine 等，通常也會希望在這些專案管理工具上，查看某一個工作事項，與之關聯的 GIT Commit 有哪些，反之，也希望在 Commit 看，就可以看出該 commit 是基於什麼工作事項而變更，那讓 commit message 可以與這些工具自動的建立起關聯，便可以幫助專案的進行更加的順暢。

Conventional Commit 中定義的 commit message 大致上如下，細節可以參考官方網站上，上面有中文等多種語言可以查看：

<type>[optional scope]: <description>

[optional body]

[optional footer]

• type 的部分包括但不限於以下幾個類型：fix:, feat:, BREAKING CHANGE:, chore:, docs:, style:, refactor:, perf:, test:

個人實務經驗

以我個人自己實務的使用來說，通常會基於上述的七項原則，再做一些修改，畢竟 commit message 對於專案來說，最重要的原則是讓專案成員都可以看懂，讓會接觸到這個 commit 的人都讀懂。因此根據專案成員的特性，有時候會有像是幾個變更：

1. 允許使用中文。如專案成員只會有講中文的人，大家的母語都是中文，那用英文撰寫可能會造成一些訊息宣示上的障礙。
2. 標題字數限制改變，提升到 70 字元。字元的限制我認為，只要是要讓團隊成員都可以在一般的視窗寬度下完整讀完第一行訊息即可。
3. 不強制一定要撰寫內容(body)。有時候有些專案需求的修改，僅需要在標題上描述，就足夠清楚時，強制編寫內容可能就沒必要。
4. 7 rules 混搭 Conventional Commits，在第一行加上一些與專案工作相關的字樣，讓專案管理工具也可以被自動加上與 commit 間的關聯，如 Issue Number，Issue Type 等，而後加上這個 commit 是屬於該 Issue 的什麼部分。

總結：

在專案進行的過程中，一件工作基於工作事項的大小，可能無法一兩個步驟就完成。這時候，我認為開發者，就有義務讓這個工作事項切割成更小的事物，逐一實作，而在編寫 GIT commit message 時，讓每個 commit message 只作一件事情。

畢竟 GIT 留下來的訊息，是給可以接觸到這個專案的人看的，而那個人，也有可能是一兩年後的你。別讓未來的你，討厭現在的自己。

後記：

原本 git add 跟 git commit 是要一起寫的，但一來是有事情耽擱開寫時間晚了，二來是想交代的點有點多，結果反而連 git add 都沒能很充分地寫完整。