Why I Create Atomic Commits In Git
I wrote about crafting changes into small atomic commits using Git. It looked like there was some confusion. I want to share what I understand about atomic and monolithic commits and why I create atomic commits in Git.
I got a question in Reddit by WetDynamics that "atomic commits sound nice in theory but in practice you end up with 100 commits of "extracted foo into a method" or "refactored bar to make it more readable". Does it really make your git history easier to grok than a single commit focused on a feature?"
I think we are on the same page. I feel as though my intent was not clear in my previous post.
An atomic commit
Let's say I do a refactor but I also update a some features and add new ones.
In an atomic commit, I will commit the refactor and each feature change separately.
I don't know what the official definition is but to me an atomic commit is a commit that focuses on one context and one context alone. Granted, this is tricky. I do this to the best of my abilities but I don't always get it right.
Disclaimer: I don't intend that I commit each and every single line or function. By context I mean a single topic: a feature, bug fix, refactor, upgrade, task...
A monolithic commit
Again. Let's say I do a refactor but I also update a some features and add new ones.
The entire changeset gets committed in a monolithic commit.
Granted, it doesn't have to be a large commit. It's a commit with changes tightly coupled into a single commit. Like a tangled or spaghetti commit.
The larger the commit, the more brittle and error prone it becomes because it becomes harder to understand (even if it's well documented - I know this from my own doing), read, review and revert.
Why go atomic?
Atomic commits are easier to:
- track - I know where they are in the history.
git log --onelineshows me all commits.
git log --grep <pattern>lets me find a commit based on a partial message.
git log <commit>will jump to that commit and show previous commits.
- understand - I document each change with a commit message and elaborate with an explanation if I need to.
- read - it's a change focused on a single context which makes it smaller,
simpler and easier to read the patch
git show <commit>or
git log <commit> -p
- review - as it's a small, focused, documented change, a reviewer should be able to follow the code changes and keep their sanity.
- revert - reverting
git revert <commit>an atomic commit will not revert unrelated changes like a monolithic commit would.
What do I do?
I try working on one thing - this is not always possible, hence my previous post. This is where I use the interactive mode to my advantage. Most GUIs come with intuitive interfaces.
git add -i
- I try keep my changes as small as possible - this makes it easier for me to commit my changes once I am done especially when I go into an interactive mode.
I try to commit often - I amend my commits when I need to.
git commit -m "<message>" --amend
- I aim to be vigilant that tests pass (I get this wrong sometimes). I want failing/code tests fixed and committed as part of the context commit. Otherwise I have a "broken" commit.
When I end up littering my feature commits (features have commits in a random order) then I use an interactive rebase to move and squash the commits prior to pushing them.
git rebase -i
The goal of creating atomic commits is not to create "100 commits" but rather pragmatically craft relevant changes for a better history, cognitive load and an easier means to rollback changes.