Professional Git commit comments

Git commit comments / log messages are (may / should be) more complex than those from Subversion. They can be automatically converted into e-mails sent to other commiters or other kind of group of interest. Some Git commands and tools may generate additional commit messages. That’s why comments written by you manually, should follow some rules and guideline. Most of them are expressed in this article.

This post is based on a “A Note About Git Commit Messages_”, posted on tbaggery in the middle of March 2008. Follow to that article for more information. My point of view on writing professional Git comments follows most of the rules expressed there, but adds and changes some small things to suit my own needs. These changes are marked with coursived text.

In short:

1. Write short (fifty characters or less) summary in the first line. (new) I don’t follow this guideline to often, as I don’t find fifty characters or less enough informative especially, when we’re talking about reading comments after a year or so.
2. Write it always in the imperative (Fix bug, not Fixed bug, Fixes bug or Fixing bug). This matches up with commit messages generated by commands like git merge or git revert. There’s an alternative school of writing comments in any form except imperative to actually distinguish manual comments from those auto-generated.
3. Add one blank separation line. This is obligatory. It is used by tools like rebase and those, that are generating e-mails from commit comments, where first empty line separates e-mail topic from e-mail body. You can omit this line only, if you’re omiting anything else — i.e. your comment contains only summary text.
4. Write more detailed explanatory text in third line. Wrap around 72 characters or so, to make it looking good on command-lines, which often shows 80 characters at most per line.
5. You can use as many paragraphs as you want, always separating one from another with one blank line.
6. (changed) Don’t use hanging indents at all! They’re looking awfully, only Americans understands them and they waste a lot of space (characters) with empty, useless spaces.
7. You can use bullets, if you need. The most common pratice says, that they’re just like a paragraphs (so: each bullet in separate line, separated from another one with a blank line), uses hyphen (-) or asterisk (*) and always have one space that separates bullet character from rest of the text. They should be short, one-line, but if you need longer ones, remember to add two spaces in each following line, so bullet body starts in the same position in every line.
8. (new) _You should use a plain-text only and even avoid simple Markdown. You don’t know, if such formatting won’t break somewhere.

Taking all above guidelines into account (with my changes and additions) gives us following example of professional Git commit comment:

    Rename "main/show" action into "main/page" and add info about new content type -- "file".

    Action "main/show" was renamed into "main/page". This is temporal, dummy
    function used currently for displaying pages. It will be soon replaced
    with general content displaying action.

    Added information about new content type ("file") and that user should use
    it for displaying images, if these are needed, as real image-type content
    does not exists (isn't used) -- images purpose is solely to be previews
    of other type of media (like videos etc.).

Some other general issues (all added by me):

1. Always use English as unified, international, developer-oriented language.
2. Write in English and write comments at all, even if you’re the only committer and you’re comitting your own, personal project to your own, local repository. Comment always. One day you’ll love yourself for this, belive me.
3. Use correct, spell-checked, spelling errors-free language. Use spelling tools binded into Git clients or any dictionary. That also includes capitalized sentences, ended with dots or other sentence-ending characters and with commas and other interpunction characters, where they’re supposed to be.
4. Comment always! Five more minutes “wasted” on this may often mean an hour or so saved in the future.
5. Did I mention, that you should always write comments? :] Consider that comment-less commit is not a commit at all.

As you may see, something that most people sees as writing two or three words can often turn into larger issue. But in fact, all above guideline are simple and so obvious, that most people uses them automatically, without even knowing about them.