Do you keep a tidy Git commit history?

Ali Haydar
4 min readSep 23, 2021

Commits form one of the core concepts in git. They are snapshots of your branch at a certain point, recording your code changes. When you create a new commit, you usually add a message that describes your code changes. The commit messages are the logs of your changes.

In multiple instances, I have encountered unclear commit messages. This was frustrating, not just because of my slight obsession with quality and tidiness but also because I needed to urgently understand what was going on in this change to fix a production bug. Has this change caused the bug? Should I revert the change?

I just needed to review the project changes on other occasions, and I would appreciate clear, concise commit messages. Some of the messages I didn’t enjoy much included:

  • Update
  • Problem
  • fixing Issue
  • Adding code
  • bug fixes

Going through this type of commit message doesn’t help with anything. It might be better to allow empty commit messages instead (don’t do that).

As you can see, writing clean and tidy commit messages has lots of benefits, from enabling troubleshooting issues, reading the history, and potentially generating changelogs (I worked in teams that use the commit history to create release notes).

How can we maintain a tidy git commit history?

In this post, we will explore conventional commits and commitizen, which would help create better commit messages that communicate the intention of the code changes to anyone reading them.

I’d like to note that even with these kinds of tools and conventions, it is still possible to write unclear messages (e.g. feat: add some code to the repo). However, these tools help in the formatting and constitute a gentle reminder that commits messages are important.

Setup conventional commits

According to the documentation, the conventional commit specification is a lightweight convention on top of the commit message that provides an easy set of rules for creating an explicit commit history, making it easier to write automated tools on top of it.

The convention suggests writing the commit message in the following format:

<type>[optional scope]: <description>[optional body]
Ali Haydar

Software engineer (JS | REACT | Node | AWS | Test Automation)