loading...

Atomic Commits

jbranchaud profile image Josh Branchaud ・2 min read

An atomic commit is a commit (in a version control system like git) that can stand on its own. It is made up of changes to your codebase that do exactly one thing. It is the smallest change you can make that satisfies a feature’s acceptance criteria on some level, keeps the test suite green, and passes formatting and other CI checks. It’s solid. It’s ready to go.

Why does this matter?

A commit crafted in this way serves as a checkpoint for you. That means you can commit it and forget it as you continue to grapple with other concerns and the feature as a whole. It also means it is a safe point to revert to if you’ve coded yourself into a corner or you’ve pursued an approach that isn’t going to pan out. Disentangling lines of code that you want to keep from ones that aren’t going to work is painstaking if you aren’t making checkpoint commits — this is one of git’s biggest selling points.

An atomic commit is something you’d be proud to show your coworkers. Toxic and judgmental work environments aside, we’ve all had that moment where we pull someone in for pairing or a code review and we feel the need to explain away our mess of unintelligible (or even profane) commits. Or as you try to walk through your progress, you have trouble identifying what is relevant and why you did X. Atomic commits with good commit messages show that you’ve taken the time to organize your thoughts and are prepared to make good use of your coworkers’ time.

Atomic commits are complete which means you could hand one off at a moment’s notice. If you need to suddenly leave for the day, you could hand it off to a coworker and there is a clean break for them to pick up from. Or if business priorities shift, you could ship what you have without necessarily getting to the rest right now. The alternative is that you throw it out or it gets orphaned on a feature branch.

Making a practice of producing atomic commits is one of those things that levels you up as a developer. It makes you better at building features and it makes you a better collaborator.


Thanks to Jake Worth for providing feedback on this post.

Notes:

One of my favorite ways to review changes and produce atomic commits is the --patch flag for git commit.

Making atomic commits has its tradeoffs. The downsides of keeping commits green discussed by Kelly Sutton is worth reading in this context as well.

Posted on by:

jbranchaud profile

Josh Branchaud

@jbranchaud

I'm a developer and consultant focused primarily on the web, specializing in React, Ruby on Rails, and PostgreSQL. Newsletter: https://tinyletter.com/jbranchaud

Discussion

markdown guide