Git Commit Message - You Are Not Doing It Correctly

Most of the time people don't care about commit names and they write just some text in a message. And if I say that you need to write good commit messages 90% answers that I get is "It's just my personal project" or "Nobody cares about commit names in my team" why should I do it?

Here are some points why:

  • It makes not only your code but also your commits look professional
  • Other people will see that you are a skilled programmer
  • It's much easier to find a problem with good commit message because from code you can see the changes but not why they are needed. Only commit message can help with that
  • It's much easier to do git blame, revert, rebase and log with good commit messages

Here is an example of bad commit history and a good one. Even when we just see a short form history it's much easier to follow what was done.

Here are good list of rules which helps to write a good commit message

  • Title
  • Empty line after title
  • Body if needed. It can be just text or a list of bullet points.
  • Metadata like ticket number in issue tracker

Let's start with title.

  • It should be 50 characters or less.
  • It should summarize what you did.
  • It's important to remember that this is exactly what people see in the short form or git history. If you can't summarize what you did it means that you are not doing atomic commits. It means that 1 commit should just do 1 change not 100 changes.
  • Always you imperative form like "Add a username to register form". It's because when you use any Git command it will write you
If applied, this commit will Add a username to register form

Which means you get good structure english sentences.

Body part is not mandatory. If your change is small you can do title only. But if you need to tell people why you make this changes or what exactly did you change than you need to use body. I recommend to use bullet points list for list of changes and just plain text for telling about your change.

It's also important to remember that Git doesn't make text wrapping at all and you need to make it yourself while writing commit message. Normally it's recommented to wrap your text after 72 characters and you can configure your editor to highlight when you need to wrap your code.

Here is an example of good body

Remove the 'state' and 'exceptmask' from serialize.h's stream
implementations, as well as related methods.

As exceptmask always included 'failbit', and setstate was always
called with bits = failbit, all it did was immediately raise an
exception. Get rid of those variables, and replace the setstate
with direct exception throwing (which also removes some dead
code).

The last this is metadata. If you want with any ticket system you must include a ticket name in your commit. It simplifies finding it later. You can just write after empty line

Resolves: #123

But I like a different approach. I always include in the beginner of the title the type of the ticket and the ID. In this case I can directly write it in inline mode when I write only title and see it directly in commit history

[BUG-123] Add a username to register form

So I wrap the type and id in square brackets and write the type in uppercase.

The last thing that I want to show you is conventionalcommits projects. It's a convention how to write commit message.

https://www.conventionalcommits.org/en/v1.0.0/

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

As you can see it's really similar to what we discussed

fix(lang): Add a username to register form

Body text

Refs #123

The most interesting part here is a recommendation of what words to use to make your commits expressive.

For example "Commits MUST be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space."

Writing good commit messages is extremely important both for the support of any project and you as a developer.