a guide to writing git commit messages

The GOPW application period is coming to a close soon, and so potential interns are currently getting their initial contribution in to qualify.

Obviously the nicest way to submit your patch is as a commit, or series of commits using git, either via git bz or git format-patch (a branch is nice too, but submitting the patch in Bugzilla allows for inline review).

Of course, after your patch is correct, the maintainer is going to want to merge it into the tree, in which case you need to have a useful commit message. GNOME has some guidelines on commit messages, but here are the important dot points:

  • the first line should be a short description, no more than 72 characters and does not end with a full stop;
  • the next line should be empty space;
  • following this is an optional longer description, this should be written in regular paragraphs with full sentence structure;
  • finally if this patch fixes an open bug, there should be a link to the bug report, in a paragraph by itself.

Here are some good examples taken from Empathy:

Don't destroy MainWindow on delete-event, just hide it

This stops MainWindow being unreferenced, and prevents crashes caused by things which then try to use it.

Fixes: https://bugzilla.gnome.org/show_bug.cgi?id=659118

This one has a tag:

e-account-widget-jabber: Use GtkGrid instead of GtkTable

This works around bug #657621.

https://bugzilla.gnome.org/show_bug.cgi?id=646630

Here’s another way of doing a tag (preferred by some projects):

[contact-chooser] emit 'activate' on 'row-activated' as well

This means the selection can be activated when the treeview is focused.

Or a one-liner commit:

[contact-chooser] Move the selection up/down without defocusing the entry

Remember that your commit message is important. They tell other developers what’s changed. What a commit fixes, or does, or is meant to do, and occasionally, what it doesn’t do. Commit messages are often used by the maintainer to write the release notes. When things break, people come back looking through the code for what broke it (e.g. via a git bisect) so clear and useful commit messages are essential.

Author: Danielle

Danielle is an Australian software engineer, computer scientist and feminist. She doesn't really work on GNOME any more (sadly). Opinions and writing are solely her own and so not represent her employer, the GNOME Foundation, or anyone else but herself.

6 thoughts on “a guide to writing git commit messages”

  1. I’ve learned that the other way of doing a tag with [square brackets] is a bad idea, because git tools working with emails often can’t distinguish between mailing list names and tags and then end up deleting the tag when applying.
    So I would never use tags with square brackets and always use colons unless someone specifically asked me to do that after I had told him about that problem.

    In GNOME, we originally used square brackets, but I think by now all projects have switched to using colons.

    Last but not least: Colons just look better. 🙂

  2. Thanks for this post! Its surprising how so very few people care to follow or even know these practices. BTW, according to the git guidelines, the first line is supposed to be <50 characters.

  3. I know about that rule (and vim even hilights that), but I mostly cannot write sensible commit subjects in <50 characters.
    Maybe that's because I use C and have things like gtk_really_long_function_name() in my commit message?

Leave a Reply

Your email address will not be published. Required fields are marked *

Creative Commons Attribution-ShareAlike 2.5 Australia
This work by Danielle Madeley is licensed under a Creative Commons Attribution-ShareAlike 2.5 Australia.