Write good commit messages by blaming others
git blame, not actually blaming others.
Valuing good commits
We are motivated to do good things because they are good. But we are extremely motivated to do valuable things because they are valuable. Connecting the two makes us extremely motivated to do good things.
This is true of writing good commit messages. We have been told that writing good commit messages is good, and so it is! But unless we experience the value of a good commit message, we will not be motivated to write them. And how do we experience the value of a good commit message if we don’t read commit messages?
To this end, git-blame allows us to discover which revision was the last to change the file. But just knowing that is not good enough. We need to have a workflow that makes “blaming” easy. The fewer steps we need to take from the line of code we are trying to understand to the commit message the more likely we are to actually read the message.
Vim has a great package called vim-fugitive that, among other commands, has a
:Gblame command. With the cursor on the line of interest, type
will open the
git blame output in a vertical split.
But that’s not all. With the cursor over the commit of interest, type
opens up the commit message along with all the changes introduced in that
That’s just two steps,
K. Compare that to the number of steps
required for the going-to-GitHub alternative:
- look at the name of the file you are working on
- open project in GitHub
- look at the file name again because you forgot it
- navigate to the file of interest in GitHub
- click “Blame” button
- go get cup of coffee
- forget what you were doing
- return to your computer
- find side pane open
- click on commit title on the left
That’s 10 steps! (give or take a few)
Being able to quickly check the commit message for a line of code will make you
see the value in good commit messages. You will quickly see that
fix tests is
not a valuable commit message to the reader. And you will also notice that
squashing down commits without actually writing a cohesive message wastes an
opportunity to provide valuable context for the future developer or designer who
will be looking at that code:
We may have fewer commits, but the message hardly improved!
If you are not a Vim user, do not despair. A quick search shows that there are packages for other editors that seem to do similar things (though not exactly in the same way). I found some for Emacs, Atom, VSCode, and Sublime.
Okay, I see the value, but how do I write a good commit message?
Glad you asked! thoughtbot has blog posts that have really good advice on how to write good messages. These are two that I find particularly helpful:
You can also check out thoughtbot’s gitmessage template which provides a very nice summary of what to include in a good message. I paste it here for your convenience:
# 50-character subject line # # 72-character wrapped longer description. This should answer: # # * Why was this change necessary? # * How does it address the problem? # * Are there any side effects? # # Include a link to the ticket, if any. # # Add co-authors if you worked on this code with others: # # Co-authored-by: Full Name <email@example.com> # Co-authored-by: Full Name <firstname.lastname@example.org>