An oldie but goodie, Chris Beams writes about the secret art of writing helpful Git commit messages. Here’s why he thinks it’s so important:
If you haven’t given much thought to what makes a great Git commit message, it may be the case that you haven’t spent much time using git log and related tools. There is a vicious cycle here: because the commit history is unstructured and inconsistent, one doesn’t spend much time using or taking care of it. And because it doesn’t get used or taken care of, it remains unstructured and inconsistent.
But a well-cared for log is a beautiful and useful thing.
shortlogand other subcommands come to life. Reviewing others’ commits and pull requests becomes something worth doing, and suddenly can be done independently. Understanding why something happened months or years ago becomes not only possible but efficient.
A project’s long-term success rests (among other things) on its maintainability, and a maintainer has few tools more powerful than his project’s log. It’s worth taking the time to learn how to care for one properly. What may be a hassle at first soon becomes habit, and eventually a source of pride and productivity for all involved.
This post pairs well with a more recent post on the topic. Where Chris provides a format for consistency, Stephen Amaza takes that same idea and expands it with suggestions for how to provide a commit message with better context.
I’ve always been pretty lazy with commit messages and there’s certainly been a few times when that’s come back to bite me in some terrible and unexpected way. One trick I’ll certainly be using from now on: using the first line of the message as a title and then having a much longer paragraph that follows it if the code doesn’t make sense at a quick glance.