“Please refrain from profanity in commit messages” — Photo by John Schnobrich on Unsplash

We’ve all been there, looking through a year old repo’s commits and wondering what you were feeling in that moment. It looks like frustration, going from “Set-up base components and boilerplate unit tests,” to “Fix tests,” until we arrive at a familiar place in commit message history: “asfdasdf.” Okay, maybe by a year I mean yesterday. It happens to every developer. But, it doesn’t have to! Here’s how I try to keep things 💯 in my commit history.

Personal Projects

Always work in a branch, always squash and merge*. Then delete the source branch with your “pls pls pls” commits. Easy.

* Be careful with this in GitLab, I have had it ignore the field and throw all my glorious garbage right into master.

At Work

This is a slightly different problem, since you will likely have your branch reviewed and your colleagues can see the list of 50 commits for fixing a CSS bug (that’s a real personal example). Fortunately, we have some options!

Plan Your Commits and Amend

Spending 5 minutes breaking down your issue into sensible chunks can help you have sweet commit messages, but also look really smart. Once you have made the initial commit, say “Change CSS architecture to the one Twitter agreed on,” do not push. Before you start on your next bit that you’ve planned, make sure you didn’t miss anything. Maybe you notice a console.log left in, or a typo in a unit test causing it to fail. Git amend is here to save our message history!

git add . # Don't forget to add your changes

git commit --amend --no-edit

Amend will add your newly committed changes to your nicely messaged commit and leave the message alone. That’s too long of a Git command for me to care to remember, so in your .gitconfig you can add an alias like this:

fix = commit --amend --no-edit

I also have an alias called dot which does git add . . So when I finally get tests passing after half an hour, I can amend my original commit with just g dot and g fix . Git also aliases itself to g which is pretty cool too.

When you’ve finished your task with as many concise and expertly crafted commits as you desire, push away and you can make a PR that will impress your co-workers. Feel free to push whenever you’re done with a commit as well, just so you have things saved in the cloud, but it’s important not to amend pushed commits. That would be trying to rewrite Git history that you potentially share with dozens of other developers. Take a note from the rule book of Doctor Who on this one.

Rebasing and Merge Conflicts

The messages you see often when working on one repo with multiple developers like “Merge branch master into feature” are totally fine. Even if you have half a dozen in a row, no one is worried about you keeping your branch merge-able.

But I Push for CI to Run!

If you are getting different results from your local machine compared to your CI runner, you likely have an inconsistency in a version (cough Node). Ideally you would develop in an environment your team agrees on, and match your CI to that. You can always save a few cents and processor cycles (i.e. the environment) by running your tests locally before forcing the cloud to do it.

Tools to Help

Certain conventions can help you even further, like using Danger to make sure PR titles contain a JIRA ticket. I’m also a fan of using a pre-commit hook with Husky, since it can reject your commit, then you can amend it. That hook is also a good place to run Prettier and ESLint on your staged files.

If you don’t have these tools at work, it may be worth mentioning to your team or manager. Not only does it show really good initiative but they make people’s lives a lot easier. Be the hero your team needs!

Join our community Slack and read our weekly Faun topics ⬇