I never thought too much about the commit messages I write. There’s the obvious idea of writing clear messages, much like writing a good headline for a blog post or a good subject line for an email. Otherwise, I did whatever made sense.
Many years ago, I remember learning about CVS and version control in general. I didn’t start using it until I learned Subversion, and eventually I switched to Git.
As a primarily lone wolf indie game developer, I don’t think too much about how other people might read my source repository. I think about how I might use it, and my repo is mainly a place to make sure that major mistakes aren’t going to cost me a ton of time to figure out how to revert.
Basically, the evolution of my project is bookmarked at key points along the way. As I write more code and find I introduced a problem, I can check the diff to see how I did so. If I can’t figure it out, I have the option to throw away what I’ve done and start from a known state.
It works better if I bookmark my progress frequently and not have large commits containing what is actually a bunch of different changes.
And frequent bookmarks mean that I can give concise yet specific names to those bookmarks. I think I’m pretty good at naming what I’ve just done.
But then I found How to Write a Git Commit Message by Chris Beams, and I like what he had to say on this topic.
First, there’s the idea of the context of the change. At my day job, I think the issue I flag most often in code reviews for my teammates is naming their tests, variables, and functions in a way that gives context to what they’re doing. I especially hate test names that essentially tell me what the code already tells me.
WhenFooIsClickedThenCouponCode3IsCalled is not a good test name because it doesn’t tell me why. It just tells me what a reading of the code would tell me. What is calling CouponCode3 supposed to accomplish? THAT’S the thing that I want the test name to tell me.
WhenFooIsClickedThenItemIsPurchasedWithEmployeeDiscount would be much better. It does so by using the CouponCode3 function, which is also terribly named in this contrived example so fix that issue, too, please.
When it comes to commit messages, I see similar naming problems, but I haven’t thought much about it. But if you’re looking for a previous change, which is better:
Fixed crash bug
or
Fix crash when handling sprite rotation
Obviously the second one communicates more context. If I had to read through commit logs to find a past change, I want more commit messages that read like it.
He provides 6 other tips, and one of them is to write your commit subject line in the imperative.
It’s the reason why I found the article in the first place as this tip was shared on Twitter:
A properly formed git commit subject line should always be able to complete the following sentence:
If applied, this commit will your subject line here
For example:
If applied, this commit will refactor subsystem X for readability
If applied, this commit will update getting started documentation
If applied, this commit will remove deprecated methods
If applied, this commit will release version 1.0.0
If applied, this commit will merge pull request #123 from user/branchNotice how this doesn’t work for the other non-imperative forms:
If applied, this commit will fixed bug with Y
If applied, this commit will changing behavior of X
If applied, this commit will more fixes for broken stuff
If applied, this commit will sweet new API methods
A lot of the article deals with writing entire bodies for commit messages. Other than maybe having a separate line to indicate who reviewed the code at the day job, I’ve never found a need to write more than a one-liner for my own projects. It would be overkill to expect myself to give that much context to myself.
But I’ve otherwise been winging it up until I read this article, and the general style guidelines make sense to me, so I’ve started to adopt it.
Here’s some commit messages from early on in my raking game project:
- Android seems to not truly restart app; clear containers on startup.
- Changed to higher resolution; using brighter 3rd-party grass sprite.
- Added damping factor to individual entities to allow for custom friction.
And here’s some recent ones:
- Provide background for Ultimate Item speaker image.
- Fix weather generator so Stormy days result in Windy days more often.
- Warn player when yards are filling up with too many leaves.
They could still be better, but keeping in mind the imperative style and finishing that sentence above means my commit messages are more consistent, which makes it easier for me to write them in a way that gives context to what the change is doing and makes it easier for me to read them later when I am trying to find the one past changeset that is relevant to whatever I am working on at the moment.