back to Writing Market Image

A Smarter Way to Write Commits

Sometimes the details matter more than you realize

Jul 17, 2020

Up until a few months ago I wrote my commits the same way most developers do: "Updated README", "Changed the save method", "Fixed issue with links", and all too often "wip". I never really thought much of it, and I'll be damned if I'm going to look through a git log - or so I thought.

My friend Brent Lintner noticed this pattern and suggested I try writing all my commits starting with "because ...". I thought it was brilliant, it was an easy pattern to remember. It makes it clear - for the most part - why I'm submitting the code I'm submitting. Not that I'm expecting many people to read the commits, but sometimes coming back to code, looking at a message of why something is written can be incredibly valuable.

There is however a big limitation in this pattern, and it took another one of my developer friends to point it out. Though it explains why, it really doesn't provide much context. It had never occurred to me that doing so could be valuable. That was until, I had to do a release of a project I work on daily (which currently has about 20 developers working on it). The release process of this app (because it has several business units involved) often requires cherrypicking some commits into the main branch for deployment. While walking through the deployment steps I found myself exploring the git log, where I noticed that my friend Patrick (almostphpamous co-host) always started his commit messages with the ticket he was working on, as he said, it helps him identify what the commits were revolving around. This works wonderfully when exploring the git log, and was exactly what was missing from my commit pattern.

So I've opted to follow my own simple pattern for commit messages.

{ticket-number} - because...

By utilizing this pattern and following practices of rebasing my code before PRs are issued it keeps my commits in elegant but easy to recognize clusters. These are then easy to visualize if I'm back on deployment doing cherrypicking exploring the git log. It also makes it clear what I was working on and why I wrote or committed that selection of code. There is also some other magic inside this pattern. It provides a clear work history of the tickets I worked on, and often how much work went into each ticket (assuming I'm not doing one commit per ticket). I could easily collect this information from the git log for meetings, client follow ups etc.