Writing good commit messages(github.com)

https://github.com/erlang/otp/wiki/Writing-good-commit-messages

13 comments

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

andreasklinger14 anni fa

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?

cgdangelo14 anni fa

Just a guess, but I think it's because the message should indicate what the commit itself does, not what _you_ did to write it. For example, by merging this commit, the result is that I "Add X widget" to my code.

themckman14 anni fa

This is exactly how I describe this idea to people. I tell them to complete the following sentence. "Applying this change set will...". I've recently become less averse to verbs like fixes, updates adds, etc as I feel the sentence "The change set..." is still pretty good. The key, obviously, being you're describing the change set, not your actions.

brittohalloran14 anni fa

I think of cherry picking commits as a good scenario where this wording makes sense: "I want to... fix A, then add feature B, then change x"

ninetax14 anni fa

It's to keep in form with some automatic git messages (like merge) that output in that tense. Also that is the tense the Git project committers use themselves.

See: http://stackoverflow.com/questions/3580013/should-i-use-past...

Also the past repeats: http://news.ycombinator.com/item?id=2079612

For a good laugh: http://whatthecommit.com/

calinet614 anni fa

Well, for one, 2-3 characters shorter ('fix' vs 'fixes', 'fixed', or 'fixing')

nsxwolf14 anni fa

So far these responses don't convince me there is any advantage.

It makes more sense to me that the trouble ticket ticket should be written in the imperative and the commit message should be past tense.

highwind14 anni fa

If you are going back in time in your commits and let's say you want to go forward. It just flows better to see it as a command when going in to the future.

Xcelerate14 anni fa

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.)

4ad14 anni fa

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/...

pattern14 anni fa

Thank you for that link, I'm glad to have that data point in my head now.

At first I misread your explanation of DVCS as a patch management system and was going to say that non-imperative forms of commit summaries would function similarly. Now I understand your point, and I thank you again for explaining a useful way to conceptualize what merging multiple git commits together actually accomplishes.

foldr14 anni fa

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.

bgilroy2614 anni fa

While I agree with your analysis, an alternative view is that a commit message in the imperative form would pair well with the code fix.

With a bit of revisionism it reads like a wizard's incantation:

fix bug! ::code that fixes bug::

add feature! ::code that adds feature::

add documentation! ::comments etc.::

After all, in an ideal world, every code change would simply be the execution of the whiteboard/pencil-and-paper/planning that precedes it.

Karunamon14 anni fa

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.

activepeanut14 anni fa

There are much better tools to manage TODOs and bugs. Not to mention the visibility of commit messages outside of the dev team.

highwind14 anni fa

I think I would write "Fixes bug foo".

jpalomaki14 anni fa

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...

michaelmior14 anni fa

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

dmlorenzetti14 anni fa

One could equally well argue against using imperative, then: "Git uses imperative, so by avoiding it, you make clear which messages were human-written, and which were auto-generated."

michaelmior14 anni fa

You could make that argument, but I would lean towards consitency. (For example, git uses "Merge ..." for merge commits" as opposed to "Merged ...")

benblodgett14 anni fa

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

drstewart14 anni fa

However, the commit message should describe what the commit does, not what you did.

What happens if I apply commit X to my project? Will it "Fix bug 35035" or "Fixed bug 35035"?

Roboprog14 anni fa

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).

Roboprog14 anni fa

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 ..." :-)

pjscott14 anni fa

Yes. Verbs! Good things. (No explicit verbs in this paragraph, though.)

In any case, the comment for a class or method (or whatever) should start with a quick, concrete one-sentence description of what it is or does -- preferably starting with a verb, as you said. If you want to elaborate later, great, but everything needs the one-sentence summary. If I could tell inexperienced programmers one thing, this would be a strong contender. (Other possibilities include "Write your programs in discrete pieces that you can test in isolation, as much as possible," and "Make it work before you make it fancy.")

jpalomaki14 anni fa

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.

highwind14 anni fa

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

ajross14 anni fa

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).

michaelmior14 anni fa

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.

blinks14 anni fa

Doesn't seem like an amazing rationale; personally, I like periods -- they let me know the writer finished their thought.

LoganCale14 anni fa

If it's the end of the message, one can assume the thought was completed there.

4ad14 anni fa

The first line is usually part of an email title.

ajross14 anni fa

And periods at the end of single-sentence email subjects are ... bad?

4ad14 anni fa

Commits don't have to end the email subject, often I receive emails like this from some automated system:

  sys: commit message (issue XXX)

And in English titles never end with a period anyway.

jasomill14 anni fa

To reduce line noise, you also want to avoid people worrying about whether or not such-and-such qualifies as a "complete sentence" in English.

N.B.: Requiring complete sentences in one-line summaries isn't generally a good rule, here or elsewhere, unless you like space-wasting filler. In describing a $memberType of $objectType, "This $memberType $actionVerbs the $objectType's $relation $relatedThing." is unnecessarily verbose. And I say this as someone who generally writes only complete sentences in SMS messages.

ajross14 anni fa

I'm still not following, why would a period ("sys: commit message. (issue XXX)" be a problem there? If anything, with your example I'd argue the period makes it more readable as it makes it clearer that "(issue XXX)" isn't part of the message.

bobz14 anni fa

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.)

zxoq14 anni fa

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.

xyzzyb14 anni fa

So after you're done, go back through the commits and run your build tests.

https://www.destroyallsoftware.com/screencasts/catalog/sourc...

js214 anni fa

  git add -p
  git commmit
  git stash
  build && test
  git stash pop
  rinse && wash && repeat

azza-bazoo14 anni fa

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

nraynaud14 anni fa

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

throwaway197914 anni fa

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.

msmith14 anni fa

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...

nzmsv14 anni fa

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?

tommorris14 anni fa

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

lancefisher14 anni fa

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

eperoumal14 anni fa

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

[deleted]14 anni fa