This might be an unpopular option, but one of the parts I enjoy most about being a developer is having to debug problems. It’s always interesting because you get to be a “detective in a crime movie where you are also the murderer” to quote Filipe Fortes. Once you track down the problem you might not understand WHY that line was changed and when you look up the commit where that line was changed the commit message is something unhelpful like “test” or “fixed bug” so you don’t know if you can safely change it without the risking of breaking something else.

In this article, we’ll discuss how to improve your commits to help you solve problems with your codebase using atomic commits.

What Are Atomic Commits?

An atomic commit is a process where we create commits that contain a single, self-contained change to your codebase that does one and only one thing. The commit message will also contain a clear and descriptive message so everyone knows exactly what was changed and why even if you’re the one asking “why or why”. The “atomic” part comes from the concept of atomicity in databases and transactions, where a unit of work is indivisible and cannot be broken down further.

To boil atomic commits down to a checklist, an atomic commit:
* Contains only one logical change
* Includes a clear descriptive commit message
* Is small and focused

“Small” is a term that needs to be discussed a little more because it’s such a relative term. In this context, small might be 1 line change or it might be 100,000, but the goal is to be closer to the former than the latter. The goal is to not include “extra” changes.

Why Use Atomic Commits?

The biggest benefit of Atomic Commits is that they make tracking down the source of a change and reverting the change much simpler. It is so simple that we can usually use git revert to immediately revert the change in less than a second. If the commit contained multiple changes we wouldn’t know which ones were related and we couldn’t easily revert the change.

Atomic commits also make reviewing code much easier because instead of sifting through a massive commit with multiple changes your teammates can quickly review small commits that clearly explain what is being changed and why.

Another benefit of atomic commits is that it makes the log of your commits much cleaner and more meaningful which will help figure out when something broke or was changed. When the commit message is focused and descriptive everyone who reads the history later will be able to make sense of what’s changed and why.

Generating Atomic Commits When It’s New To You

You’re always looking to get into a flow state, and Atomic Commits seem like they’re antithetical to that concept, but there’s a way we can do both until it starts to feel like second nature and it becomes part of your flow.

Start by not worrying about the process. Just write code. Then when you get to “the end” you can start to worry about how to break up your work. You’ll want to do it logically based on the three-item checklist we gave you before.

• Contains only one logical change
• Includes a clear descriptive commit message
• Is small and focused

If you can add whole files that’s great because you can easily stage them using git add <filename>.

More likely you’ll find that a single logical change might contain parts of several different files. To handle this we can use git add -p which will launch an interactive mode to select different hunks of your changes and add them to the commit.

Then you can create your commit. When creating commit messages it’s a good idea to use something like Conventional Commits which provides an easy set of rules for creating a commit history which can then easily be used to see what was changed and why.

In Conventional Commits, commit messages are formatted using the following structure:

<type>[optional scope]:

[optional body]

[optional footer(s)]

Where <type> is generally “fix” or “feat” to represent a bug fix or feature respectively. You’re not limited to those two types but it helps to limit it to just a few so you clearly communicate what’s going on.

There’s a huge benefit to always including a body so you can look back at the commit and understand more of the intent of the change.

For example, the following commit message is helpful:

fix(api): Fixed type error when creating user

But by adding a body we can make it easier to understand the intent of the change.

fix(api): Fixed type error when creating user

When a user was created with a string value
for the active state instead of an integer
it would cause an exception to be thrown.

This change adds a check to validate the
input before it’s processed.

You may have noticed the commits are limiting themselves to a fixed width. This is because some tools will cut off your message at about 80 characters so it’s always best to try and stay below 70 if at all possible.

Eventually, you’ll hit a point where working with atomic commits will be second nature to you and you’ll be able to quickly work through a change as a series of tiny changes without having to break it up later.

Pull Requests

The other “fundamental unit of change” in modern programming is the pull request. In my view, a pull request should also contain the minimal amount of changes necessary to deliver a requested functionality to your users. That means it can contain anywhere from one to an infinite number of atomic commits.

That being said I try to keep my PRs to around 100 lines of change to make bugs easier to spot and to make my reviewer happier. Atomic commits generally but not always can act as independent PRs so you can ladder your atomic commits into multiple PRs to make the review and testing process a breeze.

What You Need to Know

1. Atomic commits provide a way to structure changes to make your history easy to review and modify
2. Conventional Commits provide a way to structure your commit messages to make them easy to review
3. Pull requests become easier with atomic commits