Committing to Clarity
Tags: git, versioncontrol, versioning, software
Published: 2024-04-12 19:55:33

---
title: Committing to Clarity
published: true
date: 2023-12-27 07:45:09 UTC
tags: git, versioncontrol, versioning, software
canonical_url: https://dingdongbug.hashnode.dev/committing-to-clarity
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/r7jrvf7ylxjseix8unh9.png
---

Nowadays every developer should know Git but in case you don't (listen to me, go studying that and you will save a lot of headaches) here is a brief explanation:

> Git is a distributed version control system that allows multiple developers to collaborate on a project simultaneously without overwriting each other's work. It keeps track of changes made to files and allows users to revert to previous versions, branch out to work on new features, and merge changes back together.
> 
> The git commit message is a way to document and describe the changes being made to a file or a set of files in a Git repository. It is entered by the developer as part of the commit process and serves as a summary of the changes made.

And "Commit message" itself is the protagonist of this article.

# "Who cares"

"What should I write as commit message?"  
"Who cares"

This is what I heard many times when someone needed to write a message for a commit, with the consequence that after a few commits the repository was unreadable and unintelligible.

In small teams or individual projects, this is not a problem, however, a git repository represents the history of our code: what's been added, removed, edited, which features we merged and which ones are still in progress.

Therefore writing a good commit message should be a strict rule, even when we are working on individual projects, otherwise we are going to miss pieces of information and we will be forced to rely only on our memory.

That said, another big issue is how to standardize messages.

```bash
# 4 different commit messages for the same
> Add new String utils class
> * new String utils class
> New class: String utils
> Added String utils
```

I edited these a bit to hide confidential information, but they are real commit messages from different people working on the same repository and as you can see the style is always different.

This introduces a few issues:

* **It's time-consuming**: every time you have to think about how to format your message (What verbal tense do I use? Lowercase or not?).
    
* **Heterogeneous history**: as seen above the history is not linear due to different styles (even the same person could adopt several styles at various moments).
    

![confused woman meme](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xwf5d8ep0stru1cp2otg.png)

Hence, what is needed is a standardized way of building a commit message which can be shared among people, allowing us to write something as similar as possible to other commits.

# Solution: Conventional Commits

> The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of.
> 
> [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)

Since I discovered Conventional Commits my approach to commits changed and improved drastically. Its specification provides practical "tools" (nothing magical, but very powerful) which help developers to use git smarter and easier.

First, let's see the structure of a message:

```bash
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

# Or simply

<type>: <description>
```

So easy? Yes. The magic lies beneath the *type* argument.  
It describes the scope and context of a commit quickly and easily:

* fix
    
* feat
    
* docs
    
* refactor
    
* test
    

These are just a few examples, but all of them immediately give a hint to readers about what has been added or edited, even without knowing anything about Conventional Commits.

As stated in official website it is inspired by, and based heavily on, the [Angular Commit Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines), which include other nice features.

![Angular commit history](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/b12ck4l75sk770llnrr6.png)

Angular commit history looks so clean and easy to read.

Moreover, with this standard it is possible to automate changelogs generation and and semantic version bump (check [SemVer](https://semver.org)) while keeping git history consistent: it's a win win.

# Go try it out

In conclusion, Conventional Commits is not something you install, it's a set of rules that a team (or an individual) can adopt in its git workflow without any cost, enhancing collaboration within your development team.

By adopting this structured approach to commit messages, you can improve communication, simplify code reviews, automate release notes generation, and ultimately build a more organized and efficient development process.

So why not give Conventional Commits a shot and experience the benefits for yourself? Happy coding!