Please Start Writing Better Git Commits

Please Start Writing Better Git Commits

Your future self will thank you.

Jul 29, 2022·

5 min read

Featured on Hashnode
Featured on daily.dev
Play this article

I recently read a helpful article on Hashnode by Simon Egersand titled "Write Git Commit Messages Your Colleagues Will Love," and it inspired me to dive a little deeper into understanding what makes a Git commit good or bad.

You're probably thinking to yourself, "my commits are just fine, thank you." But are they really? Let's take a closer look.

Why Are Good Commits Important?

Git commits are like little snapshots of your code. They let you and others see what changes were made, and when. They also let you roll back those changes when something inevitably goes wrong.

That's why it's important to make sure your git commits are as clear and concise as possible. Otherwise, you run the risk of confusing yourself and others down the road.

The Problem With Your Current Commits

There are three main problems I find with many commits:

  1. They're not informative enough.
  2. They're not helpful to others.
  3. You're putting too many changes in one commit.

Not Enough Information

These commits are essentially worthless. You know the ones I'm talking about - they just say "updated" or "fixed bug" or something similarly unhelpful.

It doesn't have to be that way. Let's look at why these kinds of commits are a problem, and what you can do about it.

  1. They don't tell us anything about what was actually changed. Was a bug fixed? Was a feature added? We have no idea.

  2. It makes it harder to analyze when we're trying to find out when a particular change was introduced. If a commit just says "updated", we have no way of knowing whether it introduced the change we're looking for or not.

  3. It's lazy. If you can't be bothered to write a decent commit message, then why are you making it in the first place?

So, what can you do about it? Simple: make sure your git commits are informative. Tell us what was changed, why it was changed, and how it was changed. Use subject line wisely, and include extra information in the body. Otherwise, developers (including your future self) might just end up ignoring your commits altogether.

Not Helpful to Others

Your git commits should be helpful to others who may be working on the same codebase. That means including information that will help them understand the changes you made, and why.

Here's the problem: when you make a git commit, you're only required to provide a brief message describing the change. But that's not enough information for other developers to understand what you did and why.

As a result, many git commits are cryptic and unhelpful. The classic "updated libraries" doesn't actually tell us anything about the change that was made.

This is a problem because it makes it difficult for other developers to understand the history of a project. It also makes it hard to figure out who to blame when something goes wrong.

And we need to know who's to blame.

Too Much In One Commit

Your git commits should be concise and to the point. You want them to be informative, sure, but one wants to read a novel every time they look at the commit history. I personally have a problem writing commits that are way too long, and often have more files than I should in one commit.

I know, I know, I should be making small, atomic commits that are easy to revert if something goes wrong. But sometimes, I just can't help myself. I make a change, and it's so big and complex that I just have to commit it all at once. And then I have to go through the process of squashing all those changes into a single commit.

It's a pain, and it often leads to messy, hard-to-read commit histories. But worst of all, it can make it really difficult to revert a change if something goes wrong.

So, please, for the sake of your sanity and the sanity of those who have to work with your code, try to avoid making these long commits with multiple files. Stick to the small, atomic changes that are easy to revert.

Your future self will thank you.

How To Write Better Commits

Now that we know what makes a bad Git commit, let's look at how to make your commits better.

Make them more informative.

Your git commits should be clear and concise. That means including a proper description of what changed, and—more importantly—why it changed.

Make them more helpful.

Try to put yourself in another developer's shoes and ask yourself if what you wrote would be helpful to others who may be working on the same codebase. That means including information that will help them understand the changes you made and again, why.

There's a trend here.

Write more, smaller commits.

As I mentioned before, your git commits should be direct and to the point. Be sure to remove any unnecessary information from your commit messages, and split them up where it makes sense. Longer doesn't always mean better; keep the subject line short and move other details to the body. Smaller, atomic commits are much easier to understand and can be rolled back without affecting other working code.

Examples

Here are some examples of good commit messages:

Example 1

Remove unused CSS

Get rid of unused selectors from primary stylesheet to drastically reduce load time.

Example 2

Update README

Add a new section on how to run tests to provide more information to developers.

Example 3

Fix bug in login flow

Add a new redirect which takes users to the home page if they're already logged in, preventing users from getting stuck.

Conclusion

Writing quality Git commits is a crucial part of building a successfully project and collaborating with other developers. Your messages should be clear, concise, and helpful to others. By following these tips, hopefully you can make sure your commits are all of those things.

If you want to take it a step further, you could follow the Conventional Commits specification.

Let me know in the comments if this was helpful or if you have any questions.

Be sure to follow me for more like this!

Did you find this article valuable?

Support trav by becoming a sponsor. Any amount is appreciated!