How to make devs write better commit messages

So I know that there is a somewhat standard format of commit messages in Git, which Linus outlines here:

https://github.com/torvalds/subsurface/blob/master/README#L164

Trouble is, when most people go to commit, the file that the editor opens has no reminder of how to write a proper commit message. Often I find myself having to go back through the commit log, or consulting the above link.

I propose two things:

1.  An optional flag in the Git config that, if set, shows the format
of a typical commit message in your commit message template.

2.  The ability to modify this commit message template.  Many teams
use automated tools to read commit messages and then do automated
tasks based on that data, like comment an RT ticket.  Thus, developers
need to be reminded of these team-specific settings as well.

What are your thoughts?

The bottom line is that good commit messages are really important, so we should make it as easy as possible for developers to go ahead and write a perfect commit message every time they commit code.

E.g.

# Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit # On branch master # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # modified: application/views/layouts/layout.phtml # # Untracked files: # (use "git add <file>..." to include in what will be committed) # # public/js/databases/ # # How to properly format your commit message: # # Header line: explaining the commit in one line # # Body of commit message is a few lines of text, explaining things # in more detail, possibly giving some background about the issue # being fixed, etc etc. # # The body of the commit message can be several paragraphs, and # please do proper word-wrap and keep columns shorter than about # 74 characters or so. That way "git log" will show things # nicely even when it's indented. # # RT: 123, 456 [a comma-separated list of RT tickets this commit refers to] #

On 12/06/2011 11:55 PM, Joseph Huttner wrote:

If it's no social issue but just due to lack of a reminder you could provide a template for commit.template. Either way: you still would have to force people to set it.?

Michael Schubert <mschub@elegosoft.com> writes:

While that would be a good first step, I think people will learn best when they feel by their skin how good log messages help them in the long run.

Pick a recent bugfix in your project, analyze why the code was broken by the bug in the first place, and view the log message of the commit that introduced the code that was broken by the buggy commit. You will often notice that the original commit did not explain why the code needs to be that way sufficiently, risking later breakage, and the buggy commit that broke the code did not justify the change any more than "This happens to make something work for me in a particular narrow case".

And then look at the log message of the bugfix. Does it explain why the broken change was bad, and the fixed code _has to be_ that way?

Do this for a handful of examples, and you will start noticing patterns, and what makes good messages that become useful in the longer term. Have your people learn from good ones _as well as_ the bad ones.

Have fun.

On 6 December 2011 14:55, Joseph Huttner <huttnified@gmail.com> wrote:

Great idea! These templates would be stored in the Git repo, I assume? Btw, there is 'commit.template' which you can use locally.

 I was wondering if it might be possible to somehow add project config
defaults to one's Git repo. It would be great to have something like
'commit.template' point to a file in the Git repo by default.
Currently, it doesn't seem possible to have a config parameter "point
to" a file or directory in the Git repo. Nor do I know of a way to
have the Git repo set a config parameter to a default value. Or is
this possible after all?

Joseph Huttner:

I recently started to work with the code review system Gerrit[1]. First I did not pay attention to it, but later I was amazed that the commit message can (and should) be reviewed just like the code changes.

So if you're using a code review prozess (you should!) then also include the commit message in the review.

[1] http://en.wikipedia.org/wiki/Gerrit_%28software%29

Thomas Koch, http://www.koch.ro