Write good git commit message

For a long time I didn't know that even writing commit message can have its own "best practices". When I got in touch with git for the first time, this part was described with words like "...and here you can write something short about what's going on in the commit".

Bad commit messages

Look at the commit messages below. If you want to merge them, you realy don't know, what you are adding / changing, what they do or why you need them. The same applies if you want to search something in the history. You scroll down the log, but it is a mess and a waste of time.

How to write a good commit message

The whole message should have its format - subject, body and optionally conclusion consisting of resolved / closed issues.

Subject

The git commit help page described it very good as a single short (less than 50 character) line summarizing the change, followed by a blank line. The subject should start with a capital letter and should not end with dot. And the important thing here is, it has to be in imperative form. Chris Beams wrote a simple rule to get it right every time :

A properly formed Git commit subject line should always be able to complete the following sentence: if applied, this commit will your subject line here. For example :

if applied, this commit will Delete unnecessary files

if applied, this commit will Add grep option

if applied, this commit will Fix error when protocol is missing

It will not work for bad commit messages :

if applied, this commit will contact page

if applied, this commit will list of online users, some other changes because of server

The git itself is using this approach. When you merge something it generates a commit message like "Merge branch...", or when reverting "Revert...".

Body

Here you write what and why is changed. The body should not exceed 72 characters for a line. Of course not every commit has to have body.

Bottom line

On the end, you can add which issue does the commit fix or is related to. This can be a link, number or if you use GitHub you can write it as Resolves #N / Closes #N, where N is the issue ID.

Example

This is an example commit from one of my repositories :

Fix error when protocol is missing
First, it checks if the protocol is set. If not, it changes the url and
add the basic http protocol on the beginning.
Second, it does a "preflight" request and follows all redirects and
returns the last URL. The process then continues with this URL.
Resolves #17

Conclusion

Thank you for reading, I hope you learned something new. If you have another tip(s) how to write better commit messages, or how to better use this tool, please leave a comment.

Generate a changelog

Another advantage of such commits is it is really easy to generate changelog.

# show whole commit history
$ git log --oneline --decorate --color
# show history from one tag to another
$ git log 0.0.9..0.0.10 --oneline --decorate --color
# show history form tag to head
git log 0.0.9..HEAD --oneline --decorate --color

Commitizen

There is a command line tool available on GitHub named Commitizen which makes it a little bit easier. When you want to commit, you just type git cz and it asks you couple of questions and then creates the commit with proper message for you.

References

Comments

Sager 22.01.2018 16:39

You know, I actually disagree. I love having good standards, and I absolutely hate being confused about what is in our code base, who did it, when did they do it, and why, but commit messages are not the solution to this problem.

If you are using a tool like Github or BitBucket, you should always use pull requests. Pull Requests should contain an explanation of the problem being solved, the decided-upon solution, and the actual implementation of the solution. This should also include videos and links to external resources, when appropriate.

You can't get that from a commit message. If you are using pull requests and committing regularly and often, your commit messages will rarely be that helpful.

If you need detailed commit messages to find something you did wrong, then you are likely not committing often enough, leaving your commits too large to manage effectively.

If you need detailed commit messages to roll back to a certain version, then you should be squashing your merges into your production branch and mentioning the release name. Your individual commit messages should only live for the lifetime of development; once merged, your commits should live in the pull request for historical purposes.

To round all of my rambling up, commit messages are not that useful if you are committing many, many times a day, which I think we all should be doing. Spending time creating detailed messages is not very valuable. Use tooling and processes to make you work smarter.

Just one person's opinion!

David K 22.01.2018 20:10

I disagree with Sager. If you're making a deliberate change to your code-base, you should know why. If it takes you more than a 30 seconds to describe the change you're making, perhaps your commit is too big, or you should take some time to better understand the change your making. Perhaps that's an idealistic world and I get that it's not always going to work out that way, but I feel like that should be a goal.

In any case, ideally if a single pull request contains a single commit, sure, the commit message might be less important. But as features grow, a single PR may contain multiple commits that touch different parts of a project, and having good messages could make it easier to know which commit is a front-end change and which is a back-end, which could lead to reduced debugging times.

I will always advocate for thorough commit messages. If it takes you too long, you don't understand your code well enough, or the commit is too big.

katy 23.01.2018 04:06

PRs with well thought-out commits and commit messages are WAY easier to review.

Smithc556 16.05.2018 18:27

Hello to all, how is everything, I think every one is getting more from this website, and your views are fastidious in support of new viewers. ebfbdfdkdgaegdeb

Mackenzie 13.06.2018 06:34

Sadly, that is not usually possible - primarily due to work, which involve one's occurrence
in a certain position at a particular time.

Samira 15.07.2018 07:27

It's as difficult as you may consider, and let me make it clear the
trickiest element is taking the start.

Carroll 28.07.2018 18:58

Nevertheless, one of the finest strategies
will be to stay glued to a-one perform approach that can help you enjoy the most period feasible on a distinct equipment, promising you
a get.

couponseye 31.10.2018 10:39

thank you for this blog it was helpful to me

kavi 12.12.2018 12:44

Such a Great Article!! I learned something new from your blog. Amazing stuff. I would like to follow your blog frequently.
Keep Rocking!! |

kavi 12.12.2018 12:45

Such a Great Article!! I learned something new from your blog. Amazing stuff. I would like to follow your blog frequently. Keep Rocking!!

Mario 12.12.2018 14:19

Thanks for sharing your experience. I usually look for methods so that my collaboration is easy to assimilate my colleagues and myself in the future. Your ideas come in handy

Alex 12.12.2018 14:48

Such a good article! It opened my eyes to another ways to craft a good commit. By the way, when I'm working within a project, I use to write commits guide with tags (feat, fix and refactor).
For example:
feat: Create method for User's CRUD
fix: Update method for Article when checking article params
refactor: Valid login class method

Thanks for sharing your experience!

Orin Fink 12.12.2018 14:49

Helpful reminder! Thanks for the post. I’ve always tended toward adding the case number/ticket for the issue tracking system first but I think adding it at the end is a better idea.

Also, regarding commit msg vs pull request conversations I would argue they are both equally important and attention to one vs the other is not mutually exclusive.

Your commit messages will be the obvious comment when future team members run a history on a specific file or a blame on the file to understand how it came into the state it is in. I don’t believe pull request conversation is as easily available.

PR conversation on the other hand _is_ super helpful when taking the forward movement of the code into consideration though. It just seems the PR is a bit more transient. This of course is all just my take on things.

Amokrane Chentir 12.12.2018 14:57

To the peeps who think that writing deliberate Git commit messages is a waste of time (and that those information should rather belong to the Pull Request), consider these three points:

1. What happens if you migrate from BitBucket to GitHub? That's right, all that knowledge will be lost. This won't happen if you keep that knowledge in your commit messages. By the way, commit messages are generally used to fill the PR description box. So you don't have to do the same work twice.

2. There are real advantages in having an overview of the latest changes by just printing the git log. Consider for instance the automatic generation of Changelog.

3. Writing deliberate commit messages sets a good habit of taking the time to synthesize the change made, and reflect on it.

I only see advantages in doing that, all I hear from people who say that it's not necessary are "excuses".

Andrew 12.12.2018 15:15

I wholly agree with this post, and Amokrane Chentir's points above.

I also wrap the body of the commit to 50 chars, since it makes it cleaner when viewing in the terminal.

Thomas Edwards 12.12.2018 15:17

Good PRs vs good commit messages: why not both?

JD Kaplan 12.12.2018 15:32

I really like about 99% of this. The part I absolutely dislike is:

"And the important thing here is, it has to be in imperative form"

If I were talking about a commit with someone in person I would never use the imperative form. I'm describing what the commit does, not telling them what to do. I always want my commit messages to read comfortably and as if I were speaking to the person.

rithu rawat 12.12.2018 15:49

Outstanding blog thanks for sharing such wonderful blog with us ,after long time came across such knowlegeble blog. keep sharing such informative blog with us.

Mattias 12.12.2018 16:03

I agree with JD Kaplan here.

Even the example in the article isn't imperative. Only the first line is, not the rest.
Wouldn't imperative form be used there as well if it was easier to describe the commit that way?

I really have no problem using either one, but the way we work at my company, we almost never talk about commits that way "If applied, this commit will...". We do talk about them in past tense though.

amir 12.12.2018 16:12

I dunno about anyone else, but I think `Add error message if something went wrong` is a horrible commit message

Something went wrong? Very helpful

Mikel 13.12.2018 06:57

JD, Mattias, as with code style guides, the point is that there is a standard, to avoid such bikeshedding.

Reading between the lines, it seems like JD is arguing for third-person present, and Mattias is arguing for third-person past tense.

It doesn't matter what the standard is, just that we have one.

Imperative is the standard.

As a bonus, it works out to be shorter, which helps when the first line needs to be ~50 characters.

Damiano 13.12.2018 08:20

And using a convention to enforce good commit messages: https://github.com/conventional-commits/conventionalcommits.org

trusted 28.01.2019 14:23

Hi there just wanted to give you a quick heads up.
The words in your content seem to be running off the screen in Firefox.
I'm not sure if this is a formatting issue or something to do with browser
compatibility but I thought I'd post to let you know.
The layout look great though! Hope you get the issue resolved soon. Thanks