DEV Community

Cover image for How to make a good `git commit`
Michelle Mannering
Michelle Mannering

Posted on • Updated on

How to make a good `git commit`

At my recent GitKon talk, I spoke about git commit and what it means to have good commits.

git commit is a command used to commit your code to a specific location; local, cloud, branch, main etc. Most developers use it when wanting to commit a fix, chunk of code, typo, or similar. When making changes to a file or files, once you are happy with them, you make a commit. It's basically like saving a file to your project. Only, instead of hitting the "save" button, you write git commit.

Commit updated

But sometimes commits are all over the place. No one knows what they mean, what files have been changed, or how often you should make commits.

I answered a few of these questions on how to make good commits, and how good commits make you a great team player.

Why it's important

Before I dive into some of the cool things you can do with commits, and what you should do, let's look at why it's important.

When writing code, many people are working in a team. Whether you're coding for your company, or committing to open source projects, you need to be mindful of your team. The key to teamwork is collaboration. If you don't know what your team is doing you can't be successful.

Your commits help tell your team (and remind you) about what you're doing. What code you are writing, features you are working on, and bugs fixed.

If your commit messages are all over the place it's hard to know what's going on. Projects take more time to get off the ground, and your bus factor is SUPER high. For example, this is a mess:

No commit messages

It's all committed on the same day, and there's very little information about what the commit is.

Instead, if your commits are good, then everyone is on the same page, products are shipped quicker, and your customers are happier... and so are you!

So what makes a good commit?

Good commits

It's important to keep a few things in mind when making commits.

Firstly, you want to make regular commits. Your commit history allows you to go back to a specific 'save' point in your project. If there are horrible bugs or breakages in your code, you can revert to a 'previously known stable version'. If you haven't made regular commits, then you won't be able to do this easily.

When making commits, it's also important to be specific, and understandable. This is where we come to commit messages. When you make a commit, unlike simply "saving" a file like a Word doc, you add messages to your commits. These are called commit messages.

Writing commit messages

When you save a file on your computer, it just 'saves'. You can't add information to it. The beauty of git is you can add notes to your 'saves'. Every time you commit your code you should add a commit message.

carbon

Commit messages help you and your team understand what your code is doing. Why are you 'saving' your code at this point in time? What lines are you adding? What do they do? And yes, as in the example above, you can write lines of commit comments using -m multiple times.

Writing good commit messages helps you and your team understand what that save point is. This is helpful if you need to revert to a previous 'save' version. Or if you happen to go away on holidays everyone knows what you committed without you asking.

Someone asked during my session for some good commit examples. You might already have best practices within your organisation or community for what to write in a commit message. Short descriptions with a line or two about what you've done are helpful.

Here's a couple of my commit messages as examples:

Detailed messages

There's lots of great examples out there. Chris Beams for example has a great article on how to write a commit message. Beams says to keep in mind rules such as separating the subject and body, and explaining what the commit is about. Read the full article for all seven tips!

The main thing to keep in mind is it's okay to ship and learn πŸš€. If you worry about your commit message so much that you end up not committing anything, that's not useful either. Ask for feedback, and check what other commit messages on the project for guidance.

The TL;DR

If you don't have time to read all this, just remember three things when you make commits. That is to make your commits:

  • Timely
  • Specific
  • Understandable

Take the commit challenge

Next time you are writing a commit message, ask yourself some questions:

  • β€œWill my team understand what I’ve done?"
  • β€œWill I understand what I’ve done?"
  • β€œCan everyone in my team, including non-developers understand what I’ve done?"
  • β€œAm I being a good team player?” β€œAm I communicating well?”

If you ask these questions, then you should have amazing commit messages ❀️ Everyone will love you for it, and your projects will be much tidier and understandable.

Now, go make the world better, one commit at a time.

Header image by Arian Darvishi via Unsplash.

Discussion (13)

Collapse
donut87 profile image
Christian Baer

Why are you so fixated in writing what you did? The 'What' is perfectly visible in the diff. I can see, that you updated the README. What I do not see is 'Why'. Why did you add that information? More often than not the why is more interesting and tells a better story than the what.

Collapse
190245 profile image
Dave

If you're working for a company (and therefore a repository shared amongst a team) - the "why" is often "because there's a ticket that needs doing."

For that, we use the ticket reference as the branch name (feature branching, in effect). That one piece of information, tells the reviewer "why" that change is being done, and allows them a convenient way to check the "what" vs the requirements given.

So we actually use the git commit as "a non-technical summary of the change" - which later in the build/release pipeline, we collate commits between release X and Y, build a changelog from the commit messages, and notify others in the business.

The "what" is the diff, the "why" is the ticket we're working on, the commit message itself then tells others in the business "when" this feature was available to them. We get a human readable changelog for free, just by making commits.

Collapse
donut87 profile image
Christian Baer

I know this strategy and it is better than, 'Updated README'.
Unfortunately ticket references might be short lived (new ticket system) or not always accessible (only available online and with vpn). So I would not rely too heavily on this.
Short non technical description sounds good though.

Thread Thread
190245 profile image
Dave

If a new ticket system comes in, a new feature branch (from the previous feature branch) is easy.

If the ticket system isn't available, remote changes probably aren't either, so a PR / MR isn't possible.

Thread Thread
donut87 profile image
Christian Baer

Yeah, but the code and the repo is there. I can work, but not understand the commit πŸ˜‰

It's a bit of an edge case, but living in Germany and traveling by train teaches you not to rely on your internet connection πŸ˜…

Thread Thread
190245 profile image
Dave

Isn't that the edge case that gave rise to the ability to edit commit messages after the fact? ;)

Collapse
mishmanners profile image
Michelle Mannering Author

The key here is making sure whatever you are doing is understandable to your team. The "Why" is a perfect example of what you are doing. I love this! If you team hows what and why this is a great example of being a team player ❀️

You are the perfect example of making the world a better place one commit at a time!

Collapse
mishmanners profile image
Michelle Mannering Author

I think this line in the article sums this up: "Why are you 'saving' your code at this point in time?"

If you think I should be more explicit let me know and I'll add it in πŸ˜„

Collapse
hasone profile image
HasOne • Edited

So informative, I love it! I do commit like:

git commit -m '[ADDED] button component added'
git commit -m '[FIX] now button component accepts margin as props'
git commit -m '[TYPO/REMOVE/REFACTOR] .....'
Enter fullscreen mode Exit fullscreen mode

I don't know if this is good way to do, but nobody complaint about it unit now on my team. thank you!

Collapse
mishmanners profile image
Michelle Mannering Author

My pleasure. Yeah this is good. It shows what is happening, and I love the fact you add a category in square brackets ❀️

Collapse
charlbarrera profile image
charlbarrera

I was making the commits as you mentioned in your post, but reviewing pr's I didn't see useful this approach, because is explicit what are you doing in your code, but no much why are you doing that code, so you can get additional information to get a better perspective.

Collapse
mishmanners profile image
Michelle Mannering Author

Yeah I love this. Definitely reviewing PRs is where you should write the information. Ie. when you have a pull request, all the information about what you are adding and WHY should be in the PR rather than each commit. The PR is often a collection of commits so having a why is super important. This is something you should have in your contribution guide if it's an open source project, and something you should have as part of your guidelines for corporate closed projects.

Collapse
ftharyanto profile image
Fajar Tri Haryanto

Is it possible to write multiple line of commit messages in vs code visually (via version control on side bar)?