10 ms·

Writing good commit messages

55 points by kaeawc 14y ago

briandear 14y ago
Tim Pope's article on commit messages is the gold standard. http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa...
- andreasklinger 14y ago
  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?
  - cgdangelo 14y ago
    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.
    - themckman 14y ago
      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.
  - calinet6 14y ago
    Well, for one, 2-3 characters shorter ('fix' vs 'fixes', 'fixed', or 'fixing')
  - brittohalloran 14y ago
    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"
  - highwind 14y ago
    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.
  - ninetax 14y ago
    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-or-present-tense-in-git-commit-messages http://stackoverflow.com/questions/3580013/should-i-use-past... Also the past repeats: http://news.ycombinator.com/item?id=2079612 http://news.ycombinator.com/item?id=2079612 For a good laugh: http://whatthecommit.com/ http://whatthecommit.com/
  - nsxwolf 14y ago
    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.
eperoumal 14y ago
Good point here, I've run in too many gibberish commit messages. He could also have mentionned "use good syntax and grammar".
highwind 14y ago
I understand the justification for the DOs. But what's the purpose of that single DON'T?
- michaelmior 14y ago
  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.
  - blinks 14y ago
    Doesn't seem like an amazing rationale; personally, I like periods -- they let me know the writer finished their thought.
    - LoganCale 14y ago
      If it's the end of the message, one can assume the thought was completed there.
- 4ad 14y ago
  The first line is usually part of an email title.
  - ajross 14y ago
    And periods at the end of single-sentence email subjects are ... bad?
    - 4ad 14y ago
      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.
      - ajross 14y ago
Xcelerate 14y ago
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.)
- michaelmior 14y ago
  Git uses the imperative for a lot of its output, so this makes perfect sense to me.
  - dmlorenzetti 14y ago
    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."
  - michaelmior 14y ago
    You could make that argument, but I would lean towards consitency. (For example, git uses "Merge ..." for merge commits" as opposed to "Merged ...")
- benblodgett 14y ago
  I agree, this post seems nonsensical to me - I always use past tense because it is a description of what I did.
  - drstewart 14y ago
    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"?
- Karunamon 14y ago
  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 14y ago
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.
lancefisher 14y ago
GitHub also recommends this style, and they format commit messages with that in mind. https://github.com/blog/926-shiny-new-commit-styles https://github.com/blog/926-shiny-new-commit-styles
azza-bazoo 14y ago
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 http://who-t.blogspot.com.au/2009/12/on-commit-messages.html
bobz 14y ago
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 14y ago
  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.
  - xyzzyb 14y ago
    So after you're done, go back through the commits and run your build tests. https://www.destroyallsoftware.com/screencasts/catalog/source-code-history-integrity https://www.destroyallsoftware.com/screencasts/catalog/sourc...
  - js2 14y ago
    git add -p git commmit git stash build && test git stash pop rinse && wash && repeat
Roboprog 14y ago
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 14y ago
  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 ..." :-)
  - pjscott 14y ago
    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.")
nraynaud 14y ago
DON'T give an advice/order without explaining the rationale.
tommorris 14y ago
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:ES https://en.wikipedia.org/wiki/Wikipedia:ESL https://en.wikipedia.org/wiki/Wikipedia:ESL
throwaway1979 14y ago
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.
- nzmsv 14y ago
  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?
- msmith 14y ago
  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-with-rebase.html http://gitready.com/advanced/2009/02/10/squashing-commits-wi...
deleted 14y ago
[deleted]

55 points by kaeawc 14y ago

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

andreasklinger 14y ago
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?
- cgdangelo 14y ago
  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.
  - themckman 14y ago
    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.
- calinet6 14y ago
  Well, for one, 2-3 characters shorter ('fix' vs 'fixes', 'fixed', or 'fixing')
- brittohalloran 14y ago
  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"
- highwind 14y ago
  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.
- ninetax 14y ago
  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-or-present-tense-in-git-commit-messages http://stackoverflow.com/questions/3580013/should-i-use-past... Also the past repeats: http://news.ycombinator.com/item?id=2079612 http://news.ycombinator.com/item?id=2079612 For a good laugh: http://whatthecommit.com/ http://whatthecommit.com/
- nsxwolf 14y ago
  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.

eperoumal 14y ago

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

highwind 14y ago

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

michaelmior 14y ago
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.
- blinks 14y ago
  Doesn't seem like an amazing rationale; personally, I like periods -- they let me know the writer finished their thought.
  - LoganCale 14y ago
    If it's the end of the message, one can assume the thought was completed there.
4ad 14y ago
The first line is usually part of an email title.
- ajross 14y ago
  And periods at the end of single-sentence email subjects are ... bad?
  - 4ad 14y ago
    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.
    - ajross 14y ago

Xcelerate 14y ago

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

michaelmior 14y ago
Git uses the imperative for a lot of its output, so this makes perfect sense to me.
- dmlorenzetti 14y ago
  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."
- michaelmior 14y ago
  You could make that argument, but I would lean towards consitency. (For example, git uses "Merge ..." for merge commits" as opposed to "Merged ...")
benblodgett 14y ago
I agree, this post seems nonsensical to me - I always use past tense because it is a description of what I did.
- drstewart 14y ago
  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"?
Karunamon 14y ago
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 14y ago

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.

lancefisher 14y ago

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

azza-bazoo 14y ago

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 http://who-t.blogspot.com.au/2009/12/on-commit-messages.html

bobz 14y ago

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 14y ago
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.
- xyzzyb 14y ago
  So after you're done, go back through the commits and run your build tests. https://www.destroyallsoftware.com/screencasts/catalog/source-code-history-integrity https://www.destroyallsoftware.com/screencasts/catalog/sourc...
- js2 14y ago
  git add -p git commmit git stash build && test git stash pop rinse && wash && repeat

Roboprog 14y ago

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 14y ago
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 ..." :-)
- pjscott 14y ago
  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.")

nraynaud 14y ago

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

tommorris 14y ago

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:ES https://en.wikipedia.org/wiki/Wikipedia:ESL https://en.wikipedia.org/wiki/Wikipedia:ESL

throwaway1979 14y ago

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.

nzmsv 14y ago
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?
msmith 14y ago
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-with-rebase.html http://gitready.com/advanced/2009/02/10/squashing-commits-wi...

deleted 14y ago

[deleted]