Git Commit message structure

Question

I am starting a new repository from scratch and I want to ensure I start off correctly. I am talking over from a previous developer who used github terribly and I want to fix it before I continue developing on to of their code.

I have done a lot of reading on github and I will be putting the repository together tomorrow. I was hoping to get your opinions on the format of the git commit message I will be using and if I am doing anything incorrect (format, too detailed etc) All my commits will be following the same format so I want to get it right.

Here's and example of one of my commit messages, thanks in advance.

"Add WIFI reconnect

Added code to force WIFI module to save and reboot if it has been over 45 seconds since a packet has been sent successfully.

This was added to fix an issue where the WIFI module lost connection to it’s network. Once disconnected it would only try to reconnect a limited number of times.

Now if the WIFI module disconnects or data has not been sent correctly for 45 seconds, a reboot will be forced and the module will try to connect and transmit on wakeup."

Answer 1

So I have decided to answer my own post using the information that all you guys have given me in your answers and replies. I am doing this because this is more of an opinion based question that can't really be answered and I would like to close it off.

I have decided that I will be adding much shorter commit messages and using the issues tracker on github (which I just discovered, thanks to you all) to hold the more detailed information. My new format for commit messages along with my issues opening and closing comments are below in case it might help someone else. Thanks again guys, I really appreciate all the advise.

Issue comment:

WIFI module loses connection to its network. Once disconnected it will try to reconnect a limited number of times before timing out.

Issue close comment:

Added code to force WIFI module to save and reboot if it has been over 45 seconds since a packet has been sent successfully. The save and reboot will occur regardless of network connection. On wakup the module will attempt to connect and transmit.

Commit message:

Add WIFI reconnect

Fix issue #1. Adds WIFI Reconnect. Now automatically attempts a reconnect if over 45 seconds since last successful packet.

Answer 2

My usual practice is to have minimal yet clear commit messages, to make history short. Just imagine looking over the git log of a file that has similar commit messages to yours, it's like reading the book.

On the other hand, some problem fixes needs more elaboration and explanations, that's where issue tracking comes in. You can mention the issue number in commit message for a reference. Github even allows to automatically close the issue when you provide the magic phrase in commit message and push the change.

Of course, every developer has it's own style, and this question is absolutely opinion-based.

Answer 3

Writing a good commit message is important, and it's fantastic you're putting so much thought into it. In general, the rule of thumb is to write in present tense and to write short, descriptive messages.

Maybe more importantly, commits should hold small and logical units of work. It appears in your example that the code encompassed in that commit could be a lot of code, maybe too much. Your example looks like a great merge commit, or merge/squash commit message.

So, smaller commits, present tense short messages, only use the extended description when necessary.