Writing Better Commit Messages

My goal with this blog post is to leave you with NO excuse for not defining a commit message convention for your team. I’m going to explain the reasons why you should define a git commit message convention, and share detailed instructions to help you move this task from your “to-do” list to “done” in a few simple steps!

A well-organized commit message history leads to more readable messages that are easy to follow when looking through the project history.

$ git log is a beautiful and powerful command — Suddenly, navigating through the log output become a possible mission!

Embracing a commit message convention will also help you properly use other git commands like git blame, git revert, git rebase, git shortlog and other git subcommands.

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.

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

A scope MUST consist of a noun describing a section of the codebase affected by the changes (or simply the epic name) surrounded by parenthesis. Example:

Short description of the applied changes.

Use the body to explain what changes you have made and why you made them.

Use this section to reference issues affected by the code changes or comment to another developers or testers.

Lets take a look at another commit message:

Now for some reason you have to remove support for polish language — all you have to do is to revert the above commit, as mentioned below:

Voila! Writing better commit messages not only keeps your commit history structured but also let you squeeze the most out of git utilities 😎

Following is the ready to use template that you can easily import in your repositories and customise as needed.

For proper source code management and better housekeeping a commit should be a wrapper for related changes. For example, fixing two different bugs should produce two separate commits.
Small commits make it easier for other developers to a) understand the changes b) roll them back if something went wrong.

Committing early and often keeps your commits small and helps you commit only related changes. Moreover, it allows you to share your code more frequently with others and avoid having merge conflicts.

Resist the temptation to commit something that you «think» is completed. Test it thoroughly to make sure it really is completed and has no side effects (as far as one can tell).

Git lets you pick from a lot of different workflows: long-running branches, feature branches, merge or rebase, git-flow, etc. Which one you choose depends on a couple of factors: your project, your overall development and deployment workflows, etc. However you choose to work, just make sure to agree on a common workflow that everyone follows.

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

Related posts:

No lights are on. The house is silent, except for the basement, and only in the very back corner of it. The whir of pedals, moving a steel wheel, all in one place. There’s sweat dripping down it’s…

Tree service companies can be very useful in a variety of different situations. Whether you’re a homeowner, a business owner, or a local government agency, there are many different reasons why you…

With growing competition in almost every sector, it is not unusual to find even established businesses trying to find ways to keep themselves “relevant” among their customers. Sometimes, these…