Writing good commit messages

[briandear]

Tim Pope's article on commit messages is the gold standard. http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa...

[andreasklinger]

Naive question: The present tense/imperative form is a standard i kind-of adopted without ever questioning.

Why is better to write in that form?

[Xcelerate]

The imperative form makes no sense. You're not commanding that something should be done -- you're telling what you have done. Unless there's a compelling reason to violate the typical rules of grammar, I will stick with past tense (or alternatively "fixes", "updates", etc.)

[4ad]

Imperative form is recommended in Git documentation itself and it's what the Linux kernel uses[1].

It makes a lot of sense if you don't view DVCSes as a fancy history mechanism but as a patch management system. Here, take this bunch of patches. What will I do if I'll merge them? I'll fix X, add option Z and port Q to ARM. Now let's say I also want to backport some patches to a stable branch, I'll take one from this branch, some from others and I'll fix X, fix Y and fix Z, but on ARM nothing works without the ARM commit, so on that branch I'll port Q to ARM.

[1] http://git.kernel.org/?p=git/git.git;a=blob;f=Documentation/...

[foldr]

I think the "imperative" here is actually better understood as the bare infinitive. (Of course, the two are morphologically identical in English, so you can't see the difference.) My guess is that in a language with a morphologically distinct imperative form, it would sound downright weird to put the commit message in the imperative, but it would sound fine to use the infinitive. For example, Spanish has a distinct imperative, but I've noticed that signs, instructions on shampoo bottles, etc., generally use the infinitive.

[Karunamon]

Came to say exactly this. If I see a commit message along the lines of :

    Fix bug foo

I'm going to assume that there is a bug that exists in this release that the author intends to fix later. Kind of like a TODO, which is what it sounds like.

[jpalomaki]

I think the imperative form feels better in release notes.

A random example from Chromium project[1]. There you can compare to get a feeling, because they are using both forms.

[1] http://www.chromium.org/getting-involved/dev-channel/release...

[michaelmior]

Git uses the imperative for a lot of its output, so this makes perfect sense to me.

[benblodgett]

I agree, this post seems nonsensical to me - I always use past tense because it is a description of what I did.

[Roboprog]

Commit messages? Your developers write commit messages???

If I run a log on a file, and each commit has a sentence, I am a happy man. But of course, I'm talking about work, not an open source project.

FYI: a more useful corporate standard is to reference a trouble ticket, although having a descriptive sentence certainly helps (when you can get your team to type anything at all, without a trigger to force it).

[Roboprog]

Which leads me to another pet peeve: javadoc comments.

Too many times I work on legacy code that where one third or less of the contents have comments -- HUGE, flowery blocks, and the rest have NOTHING.

I'd much rather have a short sentence starting with a verb, and not "this method will endeavor to attempt to proceed to ..." :-)

[jpalomaki]

Sometimes it feels it might help if one would start by writing the the commit message and then proceeding with the code edits.

Might be also good to see the summary line all the time - in the editor just to keep myself focused.

[highwind]

I understand the justification for the DOs. But what's the purpose of that single DON'T?

[ajross]

I saw that too and did a double take. A single-byte delta in a human readable string that in most cases corresponds to correct English grammar (good commit summaries are almost always phrased as a command: "Check blobdinger arguments in frozzle()." "Don't emit the grip command when we're in mouse mode.") is... a high-priority DON'T rule for commit messages in general?

This is aesthetic nonsense masquerading as objective advice, and it makes me want to doubt the rest of the items too (though honestly most of them seem fine). I never understand why people are so drawn to this kind of silliness. It's like arguing if there should be a space between "if" and "(" (and yes, I've seen people do that too).

[michaelmior]

Given that the summary should be a single phrase, I find a period redundant and when doing git log --pretty=oneline, it looks nicer without the period.

[4ad]

The first line is usually part of an email title.

[bobz]

Wow, just learned git add -p

That is fantastically useful.

*(Walks you through "hunks" (finer granularity than files) and asks if you want to stage them.)

[zxoq]

While useful, it's very dangerous in that it's serendipitous to make a commit that breaks building the project, which in the future will break building the project when checking out old commits, or introduce some subtle bug, which breaks other tools like bisect.

Just a personal preference, but I strongly prefer being able to build (and test) every commit in the entire history.

[azza-bazoo]

I was hoping for less "here's how your commit message should be formatted", and more "here's what your message should say". Though at least the blog it links to[1] discusses the latter.

No guidance on how many changes should make up one good commit (versus several)? No rules on referencing the issue tracker, or changes made by other contributors? No suggestions for when to put useful information (like "always do x when calling y()") in the commit or in a wiki or something?

[1] http://who-t.blogspot.com.au/2009/12/on-commit-messages.html

[nraynaud]

DON'T give an advice/order without explaining the rationale.

[throwaway1979]

I'm all for good commit messages. What I find frustrating is that it seems to go against the "check-in often" mantra. I probably over check-in ... many times a day. A feature might be 3-7 days or work. I try to make my commit messages describe the specific change I made during that particular check in. However, I feel no one would really care about commit messages like "Added extra param to method Foo to remove global X.

[msmith]

One nice thing about git is that you can easily amend your commit history. If you've done several related refactor commits in a row, then sometimes it makes sense to squash them into one, using `git rebase -i` [1].

[1] http://gitready.com/advanced/2009/02/10/squashing-commits-wi...

[nzmsv]

What about having a "quick commit" branch for the tiny changes and once a day merging the changes into a slower-moving "batch commit" branch with a more lengthy message?

[tommorris]

To see how not to do it, I'd suggest Wikipedia's edit summaries. (I say that in the spirit of love as a Wikipedia admin. :D)

https://en.wikipedia.org/wiki/Wikipedia:ES https://en.wikipedia.org/wiki/Wikipedia:ESL

[lancefisher]

GitHub also recommends this style, and they format commit messages with that in mind. https://github.com/blog/926-shiny-new-commit-styles

[eperoumal]

Good point here, I've run in too many gibberish commit messages. He could also have mentionned "use good syntax and grammar".