If you’ve ever looked at a commit message and thought “what the hell were they thinking?”, this is an ode to your pain.
Ideally a commit message should quickly communicate to developers what this commit actually does. Write too little, and the message is useless. Write too much, and the info gets lost in the clutter. Even worse, you’ve wasted precious dev time on something no one will ever read.
So what is the appropriate amount to put into a commit message? I’ll get to that later, but first some examples of how NOT to do it.
How Not To Commit
I’ve seen some pretty unhelpful commit messages in my days. Here are 4 of my favorites.
4. “Fixed some shit”
At least we can tell from this message that the developer has fixed something. If this is a bug fix, there probably won’t be any breaking changes anywhere else in the code. What did he fix? No idea.
3. Too Much Information
This developer clearly wanted to be helpful. In fact he included a list of every file he changed, in the message.
I’m ashamed to admit this developer was me. At least I included a summary at the top, but it’s still bogged down in technical jargon. Unfortunately I’ve wasted countless minutes listing things that can be clearly seen in the diff in commits like these. Well, live and learn.
2. “”
The developer literally didn’t type anything.
So why is this not #1? Well it’s plausible the developer was in a hurry and simply forgot to type anything. But there is something still worse than nothing…
1. “Commit”
This takes the cake for the worst commit message of all time. It is not only unhelpful, it’s also an insult to developers everywhere. This programmer actually took the time to write a message, knowing that I would read it and waste my time as well. It literally conveys no information, and it’s only purpose is to consume 2 seconds of my life, plus the inevitable 10 minute rant that follows about what a stupid message it is.
You might ask what was actually contained in this mysterious “commit”. It contained substantive changes across several areas of the program. So good news! It does something! And the only way I can know for sure is to read through every line of code that was changed. Or just Ignore it and hope for the best, which is probably what 99% of programmers do when faced with an inscrutable commit message and pressing deadlines.
How To Commit
So what makes a good commit message?
Basically, just think about who will read it, and why. There are 3 main reasons someone will read a commit message.
1. Another developer wants to merge your branch into his own. He needs to know what area of the code base you worked on, and if any of the changes will affect his own work. This often happens at the end of the day, so be kind and clearly indicate anything that is broken in your branch so other developers know to avoid it until the problem is fixed.
2. There’s a bug, and someone needs to track it down. I’ll post another article about using git as a debugging tool, but the basic idea is to roll back to a point before the bug was introduced. To do that, the developer needs enough info to see which commit was the most likely cause. This developer may even be you later on down the road. We all like to think we don’t make mistakes, but a clear commit message can be a lifesaver when things break during crunch time.
3. Your boss wants to know what he is paying you for. This is often overlooked by developers, but the project lead needs to actually see the progress of development. If you give them a clear indication of what tasks were completed, it makes their job easier and makes them want to keep you around.
Wit that being said, what does a good commit message look like?
This commit message is simple, short, and gives all the important details in plain English. It has the following parts:
- A one line summary that tells what is being changed and how.
- A pain-English description of the reason for the change: To reduce packet size over the network.
- Any important changes that might affect other developers: The need to recreate the non-serialized parameter on the client side
- Any known issues that might affect other developers: You didn’t break those tests, I did!
And yes, ideally you never push a commit that breaks something in the build. But development is an incremental process, and it’s always better to check-in incomplete work than to spend days without a commit (as long as you communicate when the team should NOT merge your latest work).
Here’s an example of a commit of incomplete work:
The all-capitals INCOMPLETE tells developers to stay away from this branch until I’m finished working on it. Ideally this commit is just a temporary placeholder that would be squashed into a complete task later on. I’ll write another post about git branch/merge etiquette later on.
And of course some commits are so simple they only need one line to describe what’s going on. Just make sure the summary tells what is being changed and how.
Conclusion
You may have noticed that all of my recommended commit messages are also very small changes. That’s intentional. While I do think it’s okay to implement a whole class or subsystem in one commit, try to keep your scope-of-work confined to a single logical change for each commit. For example: “Implement weapon switching” would probably be ok for a single commit, as long as the job is clearly defined ahead of time, and you can complete it in a few hours. In general, if you can’t summarize what you’re doing in one sentence, you’re doing too much. Consider breaking down your work into smaller chunks that can be completed in an hour or two. This will not only help your commit messages, but also your sanity 🙂
A most excellent post.
“Fixed some shit”-> Definitely had this happen in my group before. Causes a mountain of problems when tracking down previously introduced bugs that are just becoming apparent.
When doing level-design commits in Unity I’ve found it very useful to say where you did a change since that might not be implied in the commit. I tend to go with a format like this:
– Just before first combat zone, various visuals: Cleaned up some rubble to make it look more like where the player should go.
That’s a good point ArmoredThirteen. Level design commits also benefit from the same simple guidelines. It’s especially important when working with Unity3D where it’s not obvious from the diff which portion of the level was modified. Telling what you changed in the level is crucial if you have more than one LD working on the same level and you have to merge your changes. Although it’s best to avoid having more than one person working on a given level at once, your advice will help resolve merges when it does happen.