When you do what I do, you write a lot of commit messages, but you read a lot more, and a lot of them are terrible.
It's easy to write bad commit messages. I get it. You've just found (and fixed!) a particularly nasty bug, and the last thing on your mind is re-hashing all that context you've still got bouncing around your head.
Or maybe you just made it through a truly harrowing deployment, fraught with rework, typos, and frustration. Who wants to revisit all of those failures? Just commit the manifests / configs / whatever and get on with your life.
The problem with bad commit messages is that they last. Some day, someone is going to be looking through some obscure corner of the git repository, wondering who made this change and why. That person may be you. And all you have to offer is...
commit e686205f97f47b45ccd2c0a575e4b5191134947a
Author: Past Me <hahaha@example.com>
Date: Mon Aug 15 10:54:43 2016 -0400
fix some stuff, i guess.
That's not what you want to see when you're in the middle of a git bisect call chasing down a bug, or trying to git blame a breaking change in search of a fix.
Write A Good Summary
Every commit needs a good summary. It should be short, succinct and accurately describe the essence of the changeset. Try to keep it under 72 characters.
Provide Details
After the summary, leave a blank line, and then write a more in-depth and detailed description of what's actually in the commit. This is where context goes. Why are you making this change? Is there a ticket? Any other context that might be important to understanding the changes should be included.
On the flip side, don't pontificate. Over-describing is just as bad (and useless) as under-describing. Say what you need to say, and then close the editor.
For very small or completely self-explanatory commits, you can skip the details. This situation is more rare than you'd think.
Use an Editor
I see lots of people spend hours in their editor of choice, only to cop out on the commit with git commit -m 'did stuff'
Use your editor. git commit will invoke your $EDITOR by default, and let you write a more complete message.
$ git commit
Add UTF-8 String Functions
All standard str* functions now have u8_* variants that perform the
same operations, but properly handle multi-byte UTF-8 encodings of
Unicode code points. Call signatures are identical in all cases.
Fixes #1268
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch master
# Your branch is ahead of 'origin/master' by 3 commits.
# (use "git push" to publish your local commits)
#
# Changes to be committed:
# modified: include/str.h
# modified: src/strcase.c
# modified: src/strsearch.c
# modified: src/strmanip.c
# modified: README
#
# Untracked files:
# personal-notes
#vim users get some additional help from a git-aware syntax higlighting mode that will visually separate your summary from the long description, and make it easier to see what's to be committed in this go-round.
If you exit out of the commit message editing session without saving (i.e. :q!), git will abort the commit. This has saved me a fair amount of grief over the years when I realize I'm committing multiple changesets in one commit — something you ought to try to avoid.
James (@iamjameshunt) works on the Internet, spends his weekends developing new and interesting bits of software and his nights trying to make sense of research papers.
Currently exploring Kubernetes, as both a floor wax and a dessert topping.