git commit - format?

Question

What is the recommended format to be used in git's commit messages (COMMIT_EDITMSG), if there is any?

Answer 1

It varies, of course, but a very common format is something like this (taken from http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html, that I think sums it up really well):

Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded by a
   single space, with blank lines in between, but conventions vary here

One thing it doesn't address is something I've adopted for myself, namely using short tags at the start of the firstt line to identify what kind of commit it is. That might be tags like [fix] for a bugfix, [new] for a new feature or [dev] for a commit that only affects internals. With a policy like that, it's easy to autogenerate a changelog from the commits.

Edit: Here's another good summary, from this site even: In git, what are some good conventions to format multiple comments to a single commit

Answer 2

I would not recommend large messages. If you can't explain in one sentence what you are doing, your commit encompasses too much change. Use git rebase -i and split up your commit if you already committed. If you have not committed the changes yet, use git add -p to stage in small parts and then commit as smaller commits.

A granular change history like this will help subsequent merges and rebases. It will also help you link to your issue tracker. If you have 2 or more tickets addressed, it will be more difficult to decipher what ticket each change in the commit addressed.