How to write Good Commmit Messages?

by Hetav Desai | November 28, 2020

Introduction to Git and Version Control

Version control is a tool which helps us keep track of changes that are made to our code. It tracks what changes were made, who made the changes and when were the changes made. Moreover, if we end up breaking some feature or the feature that we were trying to build doesn't work out, version control also facilitates us to move to the previous version of the code. Currently, Git is the most widely used version controlling tool.

What are commit messages and why are they important?

A commit message is a description of what changes have been made in the current commit and why they were made. It is very important to write good commit messages as they can help you track the timeline of your projects. Commit messages become even more important when there are multiple people working on the same project, so that everyone understands what is going on with the project. Hence it is a good practice to write good commit messages and follow a common template that the team agrees upon. In case of a personal project, it is not compulsory to follow any such format or template but it is always advisable to use one, as it can be very much helpful if you decide to open source your project, share it with someone seeking for their help or showcase it on your portfolio. The practice of writing good commit messages also comes in handy when you want to go through code of some other developers or want to contribute to open source.

What is a good commit message?

A good commit message is a one which very clearly conveys the changes that were made in the commit and the reasons for the same. There are number of conventions and templates that are used across the industry. I'll highlight a few basic guidelines to follow which will help you write a good commit message.

  1. Mention the type of commit
    • feat: The new feature you're adding to a particular application
    • fix: A bug fix
    • style: Feature and updates related to styling
    • refactor: Refactoring a specific section of the codebase
    • test: Everything related to testing
    • docs: Everything related to documentation
    • chore: Regular code maintenance
  2. Write your commit message in two parts: subject line and body
  3. Keep the subject line short and crisp
  4. In body, state what changes were made along with the reason for the same
  5. Provide necessary context when necessary (e.g., in case of bug fix, you could explain what the bug was)
  6. Follow the commit convention that is being followed by your team (and adapt the existing convention in case of open source contribution)

Final Thoughts

The main idea of writing good commit messages is that it should be crisp, meaningful and convey the message well to anyone reading it. Writing good commit message is a skill that can be acquired overtime. You can refer to commit messages by good developers or on some of the top open source repos on GitHub.

Thank you very much for reading this article and if you found it useful, please do share it with your friends or anyone who may benefit from this.