Writing Good Commit Messages

If you browse the log of any random Git repository, you will probably find its commit messages are more or less a mess. I am beyond guilty of this, especially if I am in a hurry or did something silly like forgetting to save a file before pushing a commit (we've all been there). Writing good, healthy and meaningful commit messages though shouldn't be stressful or time consuming. I developed a system that I've been using and it works for me.

Why Good Commit Messages Matter

The contributors to repositories know that a well-crafted git commit message is the best way to communicate context about a change to fellow developers (and indeed to their future selves). Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our efforts should go to reducing it as much as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator.

a commit message shows whether a developer is a good collaborator

There's no strict definition of the ideal commit message, but some general rules have emerged. A commit should contain exactly one logical change. A logical change includes adding a new feature, fixing a specific bug, etc. If it's not possible to describe the high level change in a few words, it is most likely too complex for a single commit. Three main reasons why good commit messages are important are:

• To speed up the review process
• To help the developer team to write good release notes
• To help the future maintainers(why such feature was added)

Commit messages frequently communicate why such a change was made, so it helps to understand better. Thus better understanding and collaboration make work more efficient. There are several good ideas to what a good commit message is or has:

• Specify the type of commit
• Limit the subject line to 50 characters
• Capitalize the subject line
• Remove unnecessary punctuation marks
• Use the imperative mood in the subject line
• Wrap the body at 72 characters
• Use the body to explain what and why vs. how

My System

Most programming languages have well-established conventions as to what constitutes idiomatic style, i.e. naming, formatting and so on. There are variations on these conventions, of course, but most developers agree that picking one and sticking to it is far better than the chaos that ensues when everybody does their own thing. I developed my own system since places I've worked haven't enforced one or had one of thier own. And when I discovered you can add emojis to commit messages, I gave them a bit of imagery to guide their taxonomy. My system is as such:

🎉 Add: for add new files or base parts
🔥 Delete: for deleting files or sections of code
🚀 Update: updating code
🐛 Fix: for bugs that are now fixed
🛠 Build: for building new features or components
✏️ Note: for updates to readmes or coding notes
🚚 Merge: for merges

I'll ususally add the taxonomy name, a few quick words on what was done. On the next line I may add more detail but nothing overkill And then since I work with a task board, I usually put a url to reference the task. I find the url task important for legacy or if I'm out one day and someone needs to reference what ws done on the project and find the exact task I was working on. It's also helpful for when bugs like to remerge from time to time. For example:
🚀 Update: color variables
added new color palette from new design
task url

A project’s long-term success rests (among other things) on its maintainability, and a maintainer has few tools more powerful than his project’s log. The most important part of a commit message is that it should be clear and meaningful. In the long run, writing good commit messages shows how much of a collaborator you are. The benefits of writing good commit messages are not only limited to your team, but indeed expand to yourself and future contributors.