How to write good Commit Messages?

My goal with this article is to explain the reasons to follow best git commit message conventions. I will also share detailed checklist for the task.

Why are good commit messages important?

Either you are working in a large organisation or working on your personal projects, writing good commit messages can save you from many "why?" and "how?" questions thus, you can focus on being more productive.

Meaningful commit messages are an indirect way of communication between folks working on same project. For an individual it results in more readable commit history. Let's say there is a need of new feature in the application. This build produces a new bug in the application that was not there before. Finding out what caused the problem can be handy if the commit messages are meaningful.

By the help of proper commit messages you can easily find out what were expected results, also you can find out which commits need to be rolled back.

If you fix a bug or add a feature you will probably completely forget about it a month or two later. It’s not a good idea to think that if it’s not clear for others, they can ask you about it. Instead, you should provide proper commit messages for people to use as a resource in their daily work.

What is a good commit message?

A good commit message should have certain qualities:

1. It should be clear and easily understandable.
2. It should be precise, not too detailed (wrote in present tense).
3. It should be unambiguous.

Example:

style : remove padding for nav pills

fix: navbar-collapse        

Atomic Commits

Good commit messages are atomic. Let's say there are 2 changes in code base, one is bug fix and other one is minor refactoring. If you have a single commit and the bug fix caused some other bugs, rollbacking the commit will also rollback the refactored code.

This can lead to problem in large projects and thus, you should practice to follow separate commits for each piece of work you do.

Short and Unambiguous

The commit message should describe what changes your commit makes to the behaviour of the code, not what you changed in the code.

You can see what changed in the diff with the previous commit, so you don’t need to repeat it in the commit message.

Defining a commit message

Git suggests a commit message should have three parts including a subject, a description, and a ticket number.

type( optional scope): subject

[optional body]

[optional footer]
        

The commit contains the following structural elements, to communicate intent:

1. Type of commit

feat:     The new feature being added 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. Scope of commit (Optional)

A scope must describe what section of the codebase affected by the changes. 

fix(orders)

feat(user-profile)        

3. Subject

Short description of the changes made in codebase in less than 50 characters. It should be written in present tense.

feat(orders): add orders detail page
        

4. Body (Optional)

The body is used to explain what changes you have made and why you made them.

• Separate the subject from the body with a blank line
• Limit each line to 72 characters.
• Do not assume assume anything, add the explanation in short.

refactor!: drop support for Node 6

BREAKING CHANGE: refactor to use JavaScript features not available in Node6        

5. Footer (Optional)

The footer section is used to reference issues affected by the code changes or comment to another developers or testers. You can use either using ticket numbers or reference id's.

fix(orders): correct minor typos in code

See the issue for details

on typos fixed.

Reviewed-by: @XYZ

Ticket Number: #157
        

6. Commit message for reverting a commit:

Let's take a look on this commit message which was made earlier.

feat(french):localise to french

ref #333        

Now for some reason you have to remove support for French language — all you have to do is to revert the above commit. you can write this commit message as follow:

revert "feat(french):localise to french"

ref #765        

Conclusion

A great format for writing commit messages can be different in each team. The most important aspect is to keep it simple, readable, and consistent. Writing better commit messages helps to keep your commit history structured.

• Make small, atomic and single-purpose commits.
• Commit early and often, it keeps commits small and hassle-free.
• Test your code before you commit.
• Agree on a workflow or team conventions.

"Thanks for reading and don’t forget to share, comment and give as many likes as possible 👏"