I’m working on an article that outlines how to write a good Git commit message, along with a variety of Git commit message conventions and rules that developers should follow. But, as I write about the best practices developers should follow, I constantly find myself in an internal discussion of what developers should not do.
I want the original article to contain a list of best practices, not a list of things not to do. So, I’ve trimmed the Git commit worst practices parts out of it and decided to list them here.
Git commit anti-patterns
What makes a bad Git commit message? What are some things developers shouldn’t do? Here’s my top 10 list:
- Don’t go beyond 50 characters in the subject line. It should be easy to succinctly describe any Git commit.
- Don’t use passive voice or past tense when you annotate commits. Always use the active voice.
- Don’t add unnecessary capitalization to the subject line. Standard rules for capitalization aside, only capitalize the first letter of the first word in subject line. Definitely don’t shout in all caps, snake_case or worse of all, SCREAMING_SNAKE_CASE. Also, don’t put a period at the end of the subject line.
- Don’t try and format your commit message with superfluous asterisks, ampersands and hash marks.
- Don’t forget that someone troubleshooting might use a Unix utility that doesn’t automatically perform text wrapping. Instead, add a carriage return in and around the 70 character mark in the body.
- Don’t describe the low-level code you wrote. If someone wants to see the code you wrote, they’ll do a git diff. Commit messages should describe context and purpose, not implementation.
- Don’t forget to separate the commit body and the subject line with a full carriage return.
- Don’t simply reference a JIRA ticket in your commit. People shouldn’t have to open a bug tracking tool to know why you made a change to the codebase.
- Don’t say something nasty about another member of the team, even if you don’t push the branch. Local commits have a tendency to unexpectedly make it into the central code base. A subject line of ‘My idiot team lead made me do this‘ likely won’t go over well in your annual review.
- Don’t go on ad nauseam in the body of the commit. No matter how brilliant your prose, the TAGRI rule always applies in the software development world.
What gets your Git goat?
This is a list of the top 10 Git commit mistakes I see fellow developers make, but it is my no means a complete compendium. As a developer, what things do see developers do with Git that really gets your goat? I’d be interested to hear what other developers see in the field, so please share your Git commit horror stories in the comments.