Sunday, September 18, 2011

What Should My Commit Log Message Contain?

Determining what to put in your commit log message can be tricky when you first start out. At its barest, the message should contain all the metadata explaining they "why" of the commit.

Here's a few good commit messages:

* Changes from nested if/elseif statements to switch for readability.
* Removes experimental code after proven not useful.

Crafting the perfect log message is something of an art. It's something that you can learn by looking at the logs of other successful projects. Git's own log is a treasure trove of excellent commit messages.

Spend a minute or two with each commit you make, and summarize the changes the same way you would as if you were explaining them to another developer siting next to you. A great rule of thumb is to write a simple, one-line sentence that tersely explains the commit and then spend another few sentences fully explaining your commit.

Another thing to keep in mind when writing your commit message is who is going to read it. If humans are the only ones ever reading your commit messages, then straight English is fine.

If a program is going to read your log messages, you need to make sure you're including all the information it expects. There are tools that can read commit logs and update third-party tools such as ticket-tracking systems to show activity on tasks.