Erin Bush

Posted on Feb 23, 2019 • Edited on Feb 25, 2019

Being intentional with commits

#git #commit #productivity

The other day I was poking around in a github repository and came across this commit message:

Not that I needed to know that much about what this person was committing at the time, but I couldn’t help but think how unhelpful this commit message would be if someone needed to understand the project.

I have also been guilty of creating less-than-descriptive commit messages - I'm sure we've all been there. If you want to see some truly hilarious commit messages you can check out whatthecommit.com.

At my work we started using Commitizen which is based on Conventional Commits specification. It took a minute to get used to but after a few days, I could see how much value it was adding to the code base.

Breaking down commit size

Because it breaks commits down into categories, it forces you to only add relevant files to one category.

Buh-bye editing 30 files and committing them all in one go. I mean, you still could do that but you will feel a slight pang of guilt every time you add a feature change in with your test changes.

After using the tool for a few days, I started thinking about good stopping points in my work where I could commit - with the intention that I could make my messages make the most sense. For example, when working on a feature that also included some refactor work, I would try to just do the refactor first, commit that, and then start working on the new functionality. Looking back at the commit messages when browsing files and seeing the type of change that was made, helps so much for granularity and for knowing what to expect from a certain commit.

More descriptive messages

While other people on the internet might have already been splitting their commit messages into subjects and bodies, I was not. I’ve now realized, the longer description in the body is so helpful for describing the nuances of the changes you have made. Even if its just for you to go over before you make your pull request, it will help you understand why you did what you in a way more thorough way - provided you actually add a thorough description.

At my work, we’ve gone a step further to create a custom command line tool that makes your pull requests for you on Github with the pull request description being a list of your git commits. At first, I was worried this wasn’t enough. How could 100 character commit messages tell you everything you need to know about the code changes? But then, I had a lightbulb moment: the commits already ARE supposed to tell you everything about the code changes. I just wasn’t making my commits well enough. Once I started breaking things down by commit category and providing better commit messages (mainly through the longer descriptions), my pull requests were back up to the level they used to be before when I would write the description myself and have subpar commit messages.

I encourage everyone to set up Commitizen and try it out for a few days. I think it will make future you way happier when you are looking back at your code and thinking, “What the heck was I thinking?”

Top comments (17)

Aivan Monceller • Feb 24 '19

I wrote a tool called golem, something similar inspired by commitizen. I made it in Go, so that I could compile it into a single binary and be able to recommend it to my fellow developers who don't use nodejs.

github.com/geocine/golem

The JIRA ID is optional, can also remove the option totally on the source code.

Drawcard • Feb 24 '19

I like this a lot - one suggestion, rename "JIRA issue(s) ID" to something more generic like "Issue(s) ID" to make it adaptable to other issue trackers (eg Github)

Cedric van Putten • Feb 24 '19 • Edited

Great post! I absolutely love the movement of making commit messages better! 😁 Don't forget to mention that the format Commitizen is using is based on Conventional Commits 😁There are also a lot of tools to do awesome stuff with these commits, like generating changelogs (example of one of my projects) or even "calculate" next semantic version (also example a project of mine).

Here are some of them!

conventional-changelog - Generate changelogs and release notes from a project's commit messages and metadata.
semantic-release - Fully automated version management and package publishing
commitlint - Lint commit messages

Disclaimer; I became one of the maintainers of Commitlint and we joined the Conventional Changelog "group" on GitHub. That basically makes me a CC fanboy I guess 😅

Erin Bush • Feb 25 '19

Awesome! I'll have to check these out. We use some linting on our commit messages as well and I think its great. Also, I've updated the post to mention Conventional commits 😄

Cedric van Putten • Feb 25 '19

Haha nice! Hope most of the developers there are like you and think it's great too 😁 I had to convince some of our developers to stop make "annoyed sounds" and embrace the new standards 😅 Again, awesome article!

Edgar • Feb 24 '19 • Edited

I personally use gitmoji-cli for my commits: github.com/carloscuesta/gitmoji-cli

It uses emojis to define the type of commit and makes your repo a lot more colourful

Example of a repo using it: github.com/RigsOfRods/rigs-of-rods

Erin Bush • Feb 25 '19

This is very fun 🐛

Siddarth Iyer • Feb 24 '19

One particular commit format I've found which works really well in creating commits with intent is the following:

{Commit message one-liner}

## Motivation

{Couple lines explaining *why* the change is being made.}

## Design

{Couple lines explaining *what* is being done. Not "how",
but "what".}

{Link to a design wiki/document for the change, if any.}

## Misc

{List of links to supporting material, if any. For instance,
a code-review link if you're using an external tool for this.}

An example toy commit message would read like this:

Add splash screen before MainActivity launch

## Motivation

Previously, on app launch, MainActivity would load and display an empty spinner
for up to 1.5 seconds while data was fetched from the server. This was
determined to result in poor UX for the user (see #54).

Therefore, we add a splash screen to display messages to the user while data is
fetched from the server to populate MainActivity.

## Design

We display a splash screen with rotating messages (new message every 2 seconds)
indicating the user to wait while the NetFetcher service gets data from the
server. Splash screen is deactivated on receiving completion event from
NetFetcher.

See Wiki-56 at <link>.

## Misc

+ Code Review: <link>

Tip: Don't create commits like this initially. Commit frequently on your local feature branch as your fancy strikes, and don't be afraid to write minimal descriptions on your messages. However, when the time comes to push your commits up to your main shared branch, rebase your feature commits into one, and write a commit message like this one.

Mihail Malo • Feb 24 '19

This is a good template for pull requests, but personally I don't recommend squishing pull requests into one commit.

Siddarth Iyer • Feb 24 '19

May I know why you recommend not squashing commits for smaller PRs? I can see it shouldn't be done for larger PRs, but for simpler single-feature stuff (which you'd get anyway on frequent integration) setting a single commit would work well. You'd have a relatively cleaner git history and quick reverts if needed as well.

Mihail Malo • Feb 24 '19

I find it better to have more commits for git-bisect.
Then it ends up being a specific incorrect refactor, which can be made an example of, by adding regression tests, mentioning it in team guidelines, adding lints etc.
When you want to revert the whole merge, you can still use a UI button or git revert -m 1 <merge-commit>.
As for full diffs, it's just as easy to diff two arbitrary points as the state before and after a single commit.
I just don't think it brings anything useful to the table.
Maybe it's appropriate to squash-merge to the release(not master) branch in a non-CD situation. Not sure.

Rachel Soderberg • Feb 24 '19 • Edited

A trick I use for even better commit messages is card numbers (something I always do when I have the choice is number my cards in the backlog). I'll write my commit messages like this:
Card #15 - Fixed issue with string concatenation showing null, ShipState set to blank if null before customer is created.

I've found that card numbers allows you to add more robustness to your commit message without being overly wordy. If you REALLY need to research the changes that went on, you have a card number, so you can go reference that for the (hopefully) full breakdown and steps that went into the card.

Phillip Dodd • Feb 24 '19

One might say you're suggesting one really commit to their commits ;)!

Ok, now that the pins out of the way: thanks for sharing this! My team is currently in the process of reworking how we handle our source control and everyone is pretty new to it... the ideas here, in addition to the tool itself, are very helpful to read.

Levente • Feb 25 '19

Hi All,
Thanks for this great article Erin!
Good to see this conversation picking up around quality commit messages because my experience is that it's not the favorite topic of developers. At least it's pretty dividing whenever I bring it up. Usually, folks working at a large company in a regulated industry (aviation, healthcare, finance, etc) get it, because they need to comply with a buch of rules.

We work on a Jira app that checks and verifies several aspects of a commit not only at push time but right on your computer at local commit time.

I talked to a developer at Philips whose team is using it. If you are using Jira and interested give this quick interview a read I made with them.

Se-ok Jeon • Sep 24 '21

Thx for this! This is really what I wanted. Helped A LOT.
Can I translate in Korean this post? If you don't mind, I wanna share this awesome post in Korean. Surely, There will be a linke directing to this original post.