In this article I make the case for following a guide or specification when entering Git commit messages. I then propose a guide that I have put together and published on Github at https://github.com/bluejava/git-commit-guide
"There is nothing permanent except change." – Heraclitus
So, you and your team manage your code changes with Git. Great! But what commit message format has your team adopted? None? A tacit agreement to "be clear and concise"? Or do you have an actual written and specified format that you all conform to?
I have been using Git for some time - and have always strived to be a good Git citizen (A good gitizen if you will… or maybe you won't…) - using short descriptive messages, atomic commits, etc. But admittedly, I had no standard or guide that I followed. Different commits sometimes used different grammatical moods ("added" vs. "adding" vs. "add") or even different words ("added" vs. "built" vs "enhanced") to refer to the same type of change.
A quick review of popular GitHub repositories reveals that most developers have a similar approach. Here are some commit messages from some popular repositories:
These kinds of change log entries are not very useful. They mostly act as "placeholders" for a dated change - and information about the nature of the change or why it was made is unclear; or must be deduced by looking at the "diff". (Not to pick on these developers or these projects - I also am guilty of these kinds of log entries - hence this endeavor!)
The benefits of a consistent and informative change log message are wide ranging - starting with making it much easier to visually scan down commits list and find changes relevant to your search. Additionally, following a specific format opens the door to grep'ing and extracting useful information from your change logs programmatically.
It's a real productivity gain to use your commit logs to:
For large projects and/or teams this could result in huge time savings. And for smaller projects, its another opportunity to realize those cumulative benefits from multiple small improvements!
So I did some poking around and found some guides from the Atom Organization, Typo3, one derived from AngularJS by Stephen Parish, and another from the Karma project (previously Testacular - an Angular group project). These are all preceded and likely influenced by the original GIT project code contribution guide.
Essentially, these guides espouse a similar set of recommendations: recognizing some line length limits, keeping the mood/voice/tense consistently imperative, and having a standard set of types (and optionally a consistent set of scopes) that describe each commit.
Stephen's felt like the closest to what I was looking for, so that guide provided a solid basis for my first crack at a bluejava Git Commit Message Format. In fact I could very well have just adopted Stephen's guidelines as-is and improved greatly upon what I had been doing.
But there were a few changes I felt improved upon the format, so I created this derivative. Changes include:
View the complete guide here on Github. I will publish it initially as version 0.5.0 (and use SemVer conventions, as best as they apply to non-code). Once I've spent some time applying this to my own changes, I will move it to 1.0.
I encourage developers and development teams to standardize their commit messages if they haven't already. Point your team members to this guide - or fork this guide and customize it for your needs.
And of course I'd love to hear any ideas you all have to improve the format.
This is also present on the guide itself, and contained within the repository for the guide - but I am including it here too for convenience. I saved this to my desktop so I can easily display it whenever I make a commit: