編寫好 Git 提交信息的 11 個技巧

我請社區的開源從業者分享了他們關於編寫有用的 Git 提交信息的建議。

最近，當需要更新時，我一直在密切關注從產品和服務獲得的變更日誌。以下是一些示例：

• 修復了一些錯誤。
• 進行了一些可訪問性改進。
• 我們已經進行了改進，並修復了錯誤，以實現更順暢地運行。

當我想到我還是一名初級開發人員寫的一些首次提交信息時，我不得不沮喪地垂下頭：

• 用滑鼠點了一下，現在一切似乎都正常了。
• 執行了程序員 X 告訴我的操作，現在橫幅是藍色的。

這可真令人沮喪！我向我們的貢獻者們提出了以下問題：

• 什麼是好的 Git 提交信息？
• 什麼是壞的 Git 提交信息？
• 你認為一個項目應該有哪些關於提交信息所寫內容的規則？

以下是他們的答案：

易閱讀的文筆是關鍵

與你寫任何東西一樣，你應該考慮誰會閱讀它。然後相應地調整信息的數量和深度。

提高你的自然語言和寫作技能對於軟體開發的職業生涯順利發展至關重要。重要的不僅僅是代碼。

—— Camilla Conte

具有描述性，不要假設

我在 OpenStack 社區中花了很多時間合作，與我在像「野外」的其他隨意的項目中看到的相比，它的代碼審查者有一些相當嚴格的標準。

我花在撰寫一條可靠的提交信息的時間，往往要比編寫實際的代碼實現或修復程序的時間長得多。有時，提交信息可能會比它們解釋的代碼變化長很多倍。

總結一些貢獻者指導：

• 描述為什麼要做出改變，而不僅僅是改變了什麼
• 第一個提交行是最重要的（就像電子郵件的主題行）
• 不要假設審查者了解你正在修復的原始問題
• 不要假設審查者可以訪問外部 Web 服務或網站（總結缺陷報告和其他相關討論）
• 不要假設代碼是不言自明的和自我說明的（儘管沒有必要重複你在代碼注釋中也提出的觀點）
• 不要只包含與更改的早期修訂相關的信息（我們希望貢獻者將修訂壓扁在一起，並相應地編輯其提交信息）。

《OpenStack 貢獻者指南》中有一個關於該主題的 簡短章節。

—— Jeremy Stanley

未來的你會感謝自己

我非常同意 Jeremy 的觀點。+1000。

Jeremy 說：「描述為什麼要做出改變，而不僅僅是改變了什麼。」

想像一下，你是旁觀者，在遙遠的未來試圖理解這個提交。

正如老話所說，設身處地為他人著想。

—— Leigh Morresi

使用 bug ID

我建議在提交信息的開頭添加 bug ID，這樣在以後使用 grep 命令 跟蹤提交信息時就會更方便。

例如：

$ git commit -m "BZ#19xxxxx

要寫出深思熟慮的提交，請考慮以下事項：

• 我為什麼要做這些更改？
• 我的更改產生了什麼影響？
• 為什麼有更改的必要？
• 更改的依據是什麼？

—— Agil Antony

講述整個故事

我喜歡想像每個提交信息都有一個隱藏的前綴，上面寫著 「By applying this（通過應用這個）」。

一個好的提交信息包括將要發生的事情以及原因。僅僅有工單作參考是不夠的，因為這分散了信息；Git 是去中心化的。作為一名軟體開發人員，我想知道為什麼當前要考慮做出更改。正在解決的具體問題是什麼？考慮（並放棄）了哪些替代解決方案？在創建變更集的過程中發現了哪些影響當前內容的意外情況？

縮短提交信息沒有什麼好處。你未來的自己和未來的同事會感激你深入地解釋了問題，以及為什麼這個變更集是解決方案。認真學習和利用那些內容豐富的「烹飪」博客。然而，在此，僅僅是把生活經驗替換成了項目的問題罷了（LCTT 譯註：意思是要認真學習和模仿優秀、詳細的提交信息）。

—— Lisa Seelye

但不要過於冗長

一個好的 Git 提交信息包含有關所做操作的信息，而不要包含其他信息。例如，如果你需要更新 .gitignore，只需寫 「更新了 .gitignore」 即可。人們可以自行深入到提交本身中了解更多細節。它不需要冗長。

糟糕的提交信息類似於「哦，糟糕」或「試試這個」。當然，我也曾經犯過這樣的錯誤，但這對於任何需要一目了然地查看提交信息的人來說都沒有任何幫助。

提交信息的規則非常主觀。他們可能因領導和團隊而異。但至少要提供一些有關提交的上下文信息。特別是如果它是一個大的更改。沒有人有時間瀏覽 1000 多個具有大量更改歷史的文件。

—— Miriam Goldman

使用現在時

我喜歡項目經理風格的提交信息，用現在時而不是將來時的術語編寫（例如，「添加」 而不是「已添加」）。然而，這通常只有在頻繁提交時才有可能。當你面臨最後期限時，你能記住的只有「我是如何做的」而已。然而，寫得好的提交不僅有助於合作者，而且有助於提交者回憶歷史。

—— Chris Okpada

不要依賴鏈接

我想提醒同事們的一件事是，你不僅僅是向給你的提交作批准的人解釋。你還要向未來的開發人員和用戶解釋，他們在使用 bisect 或 blame 定位問題時發現了這個提交，並試圖了解其相關性。

如果提供的唯一的上下文是指向某個外部系統的鏈接，並且在未來很長一段時間內，它所鏈接的系統不再使用，或者該用戶無法訪問，那麼你的提交信息將變得無用，可能還不如空白。

我經常去挖掘一些開源項目的 Git 歷史，發現有些提交信息無非就是一個 Bug ID，或者是某個公司內部的和專用的缺陷跟蹤器的鏈接。

不要依賴鏈接！

—— Jeremy Stanley

清晰簡潔的變更日誌

作為一名發布溝通經理，我會經常閱讀整個發布版塊。我還會與開發人員會面，討論任何尚未明確的領域。然後我提前測試了版本。之後，我將通過尋找變更日誌和相應的修訂或新內容來撰寫發布文章。

變更日誌是開發人員的個人提醒，但也有相應的提議和工單。你應該適當地將產品名稱大寫，使用拼寫檢查器，與標點符號和句子結構保持一致。首席開發人員也應該校對這些。你的客戶，即開發人員，正在閱讀這些內容。在運行更新之前，他們應該了解哪些信息能更好地為客戶服務？

—— Courtney Robertson

具體一點

作為一個經常性的發布經理，我喜歡帶有組件名稱的提交的信息，以及對更改內容的簡要描述。在我們忘記了你聰明的分支名稱之後，還可以參考一下這項工作的請求來自何處，這有助於將修復程序聯繫在一起。

• 「修復致命錯誤」並不是理想的提交。
• 「ISS-304: 修復具有合作夥伴角色的用戶在登錄訪問控制功能中的致命錯誤」更好。
• 「ISS-304: 登錄訪問控制：修復 getPartnerId() 的致命錯誤」也更好。

我可以查看 Git 提交、分支、合併提交之間的整個關係，並檢查更改的各個行和文件。但我在發布過程中沒有這樣的時間。我希望能夠在項目管理工具回溯這項工作的源頭，了解哪些組件正在被更改，以及以何種方式進行更改。

—— Ryan Price

讓它成為一種習慣

我最喜歡犯的錯誤是「在我切換分支之前提交」，因為我必須處理其他更緊急的事情。有時候，我需要把我目前的工作提交給一個完全不同的項目。我的經理的策略是讓我們像平時一樣工作。但當我們變基時，他希望我們在有意義的地方壓扁提交，並編寫更好的信息。我不能說我們總是這樣做，但他的方法確實有道理。

我也有很多「這個壞了，不知道為什麼」類型的信息（哈哈），我嘗試了一些東西，但想在嘗試其他東西之前提交該嘗試，以防方法 A 比方法 B 更接近解決問題。我已經寫了 10 多年了。

—— RachieVee

你的提交信息建議或提示是什麼？讓我們在評論中知道。

via: https://opensource.com/article/22/12/git-commit-message

作者：AmyJune Hineline 選題：lkxed 譯者：ZhangZhanhaoxiang 校對：wxy

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive