Writing good commit messages | Hacker News Reader

Writing good commit messages

github.com

55 pointskaeawc49 comments

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

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?

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.

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.

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

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"

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.

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/

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.

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

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

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

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

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

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"?

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.

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

I think I would write "Fixes bug foo".

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

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

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.

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.

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.

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

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

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

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.

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

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.

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

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

The first line is usually part of an email title.

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

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.

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.

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.

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

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

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.

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

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

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

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

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

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.

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?

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

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

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

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

Reply on news.ycombinator.com