Writing Meaningful Commit Messages
Detailed commit messages are an essential part of any good development process.
Have you ever read someone else’s commit message, and wondered what on earth were they doing? Perhaps you’ve gone back and read some of your own commit messages wondering what you were doing?
At some point, most of us have fallen victim to writing commit messages that simply have no value. Perhaps you had a busy day, and didn’t have time to craft a meaningful message. Or maybe you simply felt that a commit you made didn’t warrant much detail because no one would need to circle back and read it again.
Whether it’s a matter of being lazy, or not having the time — commit messages are important. They are an communication tool that can elevate the productivity of your entire team. And when written effectively, your future self and your team will thank you for crafting such thoughtful and informative messages.
If you ask any developer to describe what an ideal commit message would look like, what would they say? Some reason, “If I commit several times a day, and I haven’t finished a feature — what am I writing about?” Others may say, “why do I need to write a commit when you can simply view the code”?
From the surface, these arguments may appear valid, but it dismisses the purpose of what commit messages are designed to do. Commit messages that are written with purpose and provide context help you get the most out of version control.
Meaningful messages do more than state the obvious, they indicate why a change happened. While anyone can simply inspect the revision history to see what has changed, it will not reveal what the developer intended to do.
Effective commit messages help you and your team understand why certain changes were introduced. Also, it simplifies the debugging process as you don’t have to review hundreds of commits to discover where a problem resides.
Imagine reading a history book, that only contained dates of when certain events happened. There was not much detail. The reader is then forced to assume much of the context of various historical accounts.
How useful would such a book be at helping the reader to discern the underlying cause and effect of problems?
Likewise, bad (or lazy) commit messages are essentially timelines that state the obvious — but leaves too much to the imagination.
What is a good commit message composed of?
Linus Torvalds (the “inventor” and main maintainer of Linux) put it this way:
A good commit message looks like this:
Header line: explaining the commit in one line
Body of commit message is a few lines of text, explaining things
in more detail, possibly giving some background about the issue
being fixed, etc etc.
The body of the commit message can be several paragraphs, and
please do proper word-wrap and keep columns shorter than about
74 characters or so. That way "git log" will show things
nicely even when it's indented.
Reported-by: whoever-reported-it
Signed-off-by: Your Name
That header line really should be meaningful, and really should be just one line.That header line is what is shown by tools like gitk and shortlog, and should summarize the change in one readable line of text, independently of the longer explanation.
While there’s no strict definition of what a commit message is, there are a few guidelines and best practices to keep in mind. Good commit messages communicate the thoughts, ideas, and possible drawbacks of a change.
Here are 3 questions to keep in mind to up your awesome when writing commit messages.
Do your commit messages answer these questions?
Why was this change made?
Did you add a new feature? Fix a typo, or a bug? Did you improve performance in some area?
For example: Instead of saying, “changed background” you could say, “Change background color based on 4/15/2015 A/B Test Results”.
What is the method behind the madness?
This simply answers why you decided to take a specific approach. Reference any online resources (like a Trello card, blog articles, etc) or relevant commits that will help provide context.
This may not be necessary to include for every single commit you make. But it should, at a very high level, explain how you decided to address the issue at hand.
What are the possible drawbacks of this change?
This is a very important question. It should contain helpful information in the event you have issues related to this commit later. It may also expose that too many changes are taking place, and you need to simplify your commit. Learn more about atomic commits.
Taking time to thoughtfully create your commit messages, are well worth the investment. Informative messages provide a peak in the mind of the developer.
They are relevant, concise, and can save you and your team from much distress down the road.
We’ve added a few more helpful links below to help improve the quality of your commit messages.
Helpful Resources