33 ms·

What a good commit message looks like (2011)

96 points by ziodave 10y ago

abstractbeliefs 10y ago
For those who aren't familiar with the kernel process, what's the Reported-by line? Simply the reporter of any original bug that the patch was written to fix? I understand that the Signed-off-by line is equivalent to a CLA, right?
- hdhzy 10y ago
  Yes and yes.
- philips 10y ago
  Yes, and many of the maintainer automations will email the reporter about the patch being merged into the various releases. And signed-off-by is essentially a shorthand for agreement to this document: http://developercertificate.org/ http://developercertificate.org/
- tych0 10y ago
  Yes, Reported-by is the original reporter. Signed-off-by is fallout from the SCO lawsuit. It has nothing to do with agreeing to any sort of CLA; it's just another way to confirm that the code was written by the person in Signed-off-by, or that the person in Signed-off-by thinks it was created under appropriate open source conditions (e.g. the company who paid the developer to write it is okay with it being released).
- deleted 10y ago
  [deleted]
Avshalom 10y ago
>74 characters path dependency is hell of a drug.
- quickben 10y ago
  People use VMs, print stuff on paper, have 10'' laptops, etc.
- merb 10y ago
  if you open a terminal window on mac with any kind of display 1080p, 4k whatever with any resolution you will still get a 80x24 terminal by default. Which is the whole purpose of `git log`. Using it on a terminal / ssh session / whatever.
  - mamadrood 10y ago
    I use ~80 cols terminal because everything is designed to fit in 80 anyway. More than that and it's just whitespace.
- raimue 10y ago
  The reason for this is that Git patches are meant to be exchanged over email. Historically email has a line limitation of 80 characters. You are supposed to use less than that to allow insertion of quoting characters in the first columns in replies.
  - marcosdumay 10y ago
    Your email client is supposed to fix this restriction in a completely transparent way. There are a few standards for that, and you can bet every client supports all of them.
    - raimue 10y ago
      Uhm, no, that is not the reality we live in. Things like format=flowed exist, but I would not say that "all" clients support that. For example Apple Mail lately got an obsession for quoted printable encoding with very long lines.
struppi 10y ago
Recently, I try to write the first line of my commit messages so they describe what the system now does, compared to before the commit. This makes reading the history much more fun. Like: Validation of email addresses now sends a test email to the user, instead of the old regex that never worked. This style does not work for all kinds of changes, but when it works, it creates a nice history of how the functionality of the system grew...
- 345678545678655 10y ago
  Looks too long to me, will end up looking bad in most things.
- TheDong 10y ago
  Including the old bit is meaningless noise there. I'd use something like "Improve email validation" or "email: send a test email as validation" or such. The body is where you can describe previous behaviour and give more details.
  - Cthulhu_ 10y ago
    Yeah that. I'd have it describe what the commit does in the subject, and both the why and how in the body: Validation of email addresses now sends a test email to the user, instead of the old regex that never worked. > Send test email to user for email address validation > > This change was done because the old regex never worked; see also {link} and {link} for more information. as an example. Ideally the header also contains a hint to the module the change was done in, etc. The linux kernel commits take this to (what comes across to me as) the highest levels.
fit2rule 10y ago
My commit messages are (usually) one-line, starting early in the sentence with the focus of the effort, and ending with a clear statement of what happened.
mojuba 10y ago
Should be noted, it is often tempting to describe everything about the change in the commit description rather than comments in the code. Remember, git commits disappear from sight pretty soon and become fossils, whereas there may be something important that should be said in the code itself.
- karim 10y ago
  I think that on the contrary, everything should be in the commit. The commit message is dated, it has an author and a context. How often do you come across stray comments which shouldn't be here because the code got refactored away? Commis are often just a git blame away anyway.
  - Cthulhu_ 10y ago
    Except when a line has been changed over a longer period of time. Although maybe I'm just not comfortable with tracking history too much, because in the applications I generally work on (customer-facing webapps) we generally don't need to look back in history too much.
- nailer 10y ago
  Also: avoid using comments where proper names would suffice: // cleans responses function zrgfy(response){ ... } should be something like: function cleanResponse(response){ ... }
  - chousuke 10y ago
    My rule of thumb in commenting is that I comment the why or how, not the what... Unless the what is sufficiently non-obvious, in which case it is usually prudent to have a really good explanation of the why, as well.
    - deleted 10y ago
      [deleted]
- 10y ago
dang 10y ago
Url changed from https://gist.github.com/matthewhudson/1475276 https://gist.github.com/matthewhudson/1475276, which (kind of) points to this.
chris_7 10y ago
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. Software should help me, I shouldn't have to help it. Why doesn't git handle this formatting automatically? I shouldn't need to manually break lines for typographical (not paragraph) reasons.
- raimue 10y ago
  That software is called a text editor and you can configure it to do the text wrapping for you. More seriously, it is quite hard to wrap text correctly after you submitted it. For example people add manual line breaks for structuring text and to separate things like quoted commands from the rest. It would be much more cumbersome to go back after a git commit to fix this, probably in multiple iterations until you get the intended presentation instead of just doing it right from the start.
  - chris_7 10y ago
    Web browsers line break text dynamically just fine - as do, well, text editors. Using a text editor to automatically embed line breaks doesn't fix the problem: embedding line breaks in text for formatting is wrong semantically. Hard line breaks should mean something. Now I can't reflow the text to display it on a web page in a normal font, because I can't be sure of which line breaks are meaningful, and which are formatting.
    - masklinn 10y ago
      Except now you need everything to handle textual contexts because while I do want my nice paragraph of text to be wrapped, I don't want my code snippet to be wrapped at all, and I want my nested list to be correctly intended at wrapping.
      - chris_7 10y ago
        Is there not precedent for handling that correctly in a plain text field?
gempir 10y ago
Great system about our commit system at work is that every commit starts with the name of a ticket of our ticket system (jira) so you can go back to that ticket whenever that commit comes up anywhere and understand the commit better
- superzadeh 10y ago
  even better systems allows to link tickets to commits.
  - gregmac 10y ago
    Not the OP, but our JIRA instance does this. From a ticket in JIRA, you can see any commits, branches or pull requests mentioning that ticket. We also use this convention with gitflow, so our branches are named eg, feature/PROJ-1234-added-new-ui or bug/PROJ-2345-fix-new-ui. This also lets JIRA find and link them, and makes pull requests get the ticket number in their title by default as well (since its based on branch name). The last bit is just a short human-readable thing to make branches easier to look at and find, because the initial way we started using gitflow: feature/ feature/PROJ-2286 feature/PROJ-2352 feature/PROJ-2367 feature/PROJ-2382 feature/PROJ-2385 bug/ bug/PROJ-2240 bug/PROJ-2323 bug/PROJ-2393 is completely unintelligible.
dallamaneni 10y ago
I made this git commit template sometime ago. Check it out if it is of any help: https://gist.github.com/adeekshith/cd4c95a064977cdc6c50 https://gist.github.com/adeekshith/cd4c95a064977cdc6c50
wruza 10y ago
Just for those who are tired of sites that disable both 2tap-zoom and 'pre' block wrapping on mobile. --- A good commit message looks like this: 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. Reported-by: whoever-reported-it Signed-off-by: Your Name <youremail@yourhost.com> where that header line really should be meaningful, and really should be just one line. That header line is what is shown by tools like gitk and shortlog, and should summarize the change in one readable line of text, independently of the longer explanation.
StapleHorse 10y ago
Relevant xkcd https://xkcd.com/1296 https://xkcd.com/1296 I once wrote "commit". A fellow coworker still makes fun of me for that, joking of course.
svckr 10y ago
Here's what, Tim Pope, our favourite vim nerd has to say about this: 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... (Same, but with more words.) A point of contention seems to be the choice of the imperative, at least for the subject line. While I'm really used to it, both when reading and writing, many people seem to strongly prefer past tense ("Fixed bug …" instead of "Fix bug …").
- Cthulhu_ 10y ago
  With that one, the way I see it is that when people use the past tense, the git history becomes a work log, i.e. what the committer did; "I fixed bug...". It shouldn't be like that, the commit should describe what the commit does, i.e. "Fix bug" or "Fixes bug". the latter uses more letters though, which is probably why I see a preference for the "Fix bug" format due to the (soft) 50 character subject constraint.
  - gumby 10y ago
    I am wary of agreeing with someone with your uname but I have to agree! Go with the project's style, but best is if that style is about the code itself. I don't care if this was easy or hard or the bug was non-obvious or if you used a weird trick. I do care what the change does: fixes a race condition, adds a new file mode etc. Those changes matter at the time (what's new in the code?) and when looking backwards (ah, here's where that new file mode was added, let's see what was going on then).
- Tarean 10y ago
  Also, when using his amazing git plugin (fugitive) to commit you get very useful highlighting when you break these conventions. http://i.imgur.com/8ix5JGa.png http://i.imgur.com/8ix5JGa.png
- gregmac 10y ago
  More importantly, the correct way is the way that is currently being used. If the project uses past tense, use it. If you want to change the convention, that's okay too, but everyone has to change. It's exactly the same issue as coding style. If you can look at code or commit messages and figure out who wrote it based purely on style/formatting, you're doing it wrong (or rather: the person using the inconsistent style/format is).
collyw 10y ago
One problem with this is that git gets used as a deployment tool as well as a version control system. Trying to get something to run on Heroku involved making lots of small changes just to get things to run on the server the same as on my dev machine. When you do that 10 or 20 times the commit message become somewhat meaningless.
- vinhboy 10y ago
  I also commit like 20 things to get Heroku working properly. But after I am done with that, I `rebase` it into one commit. Then I push it into my `origin/master`, and force push `heroku/master`.
- jtmarmon 10y ago
  generally when I'm trying this stuff I'll make a new branch to work off of and deploy from that. when I've figured out how it needs to work, I'll squash the commits and merge into master.
msimpson 10y ago
The link within that README leading to what "Signed-off-by" means is now broken. Use: https://gerrit-review.googlesource.com/Documentation/user-signedoffby.html https://gerrit-review.googlesource.com/Documentation/user-si...
binarnosp 10y ago
I open an issue for every feature, bug or enhancement, then I mention the issue in the commit followed by a short description of the changes. I wrote down a procedure that I follow for every commit [1]. This allows me to keep the commit line short and to see the commits history related to the resolution of a bug or feature. When using Gitlab, Bitbucket or Github the issues and the commits are cross-linked (example: [0]). [0] https://bitbucket.org/binarno/imebra/issues/162/ https://bitbucket.org/binarno/imebra/issues/162/ [1] https://imebra.com/wp-content/uploads/documentation/html/sop.html#sop-fixbug-2-fixing-a-bug https://imebra.com/wp-content/uploads/documentation/html/sop...
leotartari 10y ago
This is still relevant, as my friend Cesar wrote about it just the other day (with a very similar title) » https://hackernoon.com/what-makes-a-good-commit-message-995d23687ad#.5sc2xvg92 https://hackernoon.com/what-makes-a-good-commit-message-995d...
__strisk 10y ago
don't use git commit messages as "dear diary" sort of things. For example: "I fixed the button issue on the homepage. Still, need to center the title." would be better written as: "fixes button issue on homepage" Always think about what that commit does to the codebase. This is obviously for single-line commits. I suppose it would be okay to "dear diary" in the commit body. You can provide rationality or context in the commit body.
- wolfgang42 10y ago
  My recommended style is: Fix button issue on homepage This allows the title to be centered, as the button will no longer collide with it. Then, in a subsequent commit, center the title and put a reference to this one if you feel it's important, like so: Center the title on the homepage It wasn't previously because it would collide with the button, but that was fixed in f00b1f.
jordansmithnz 10y ago
Nice. At an old job, I got a little bored, so I'd spend time crafting wonderful commit messages. Most of them contained puns, some very subtle, some less so. In regards to commit ethos, I'm not sure I agree with all of the statements made. To me, something simple/concise, that others will understand, but not lacking in key info, is much better than several paragraphs explaining the same thing.

96 points by ziodave 10y ago

For those who aren't familiar with the kernel process, what's the Reported-by line? Simply the reporter of any original bug that the patch was written to fix? I understand that the Signed-off-by line is equivalent to a CLA, right?

hdhzy 10y ago
Yes and yes.
philips 10y ago
Yes, and many of the maintainer automations will email the reporter about the patch being merged into the various releases. And signed-off-by is essentially a shorthand for agreement to this document: http://developercertificate.org/ http://developercertificate.org/
tych0 10y ago
Yes, Reported-by is the original reporter. Signed-off-by is fallout from the SCO lawsuit. It has nothing to do with agreeing to any sort of CLA; it's just another way to confirm that the code was written by the person in Signed-off-by, or that the person in Signed-off-by thinks it was created under appropriate open source conditions (e.g. the company who paid the developer to write it is okay with it being released).
deleted 10y ago
[deleted]

Avshalom 10y ago

>74 characters path dependency is hell of a drug.

quickben 10y ago
People use VMs, print stuff on paper, have 10'' laptops, etc.
merb 10y ago
if you open a terminal window on mac with any kind of display 1080p, 4k whatever with any resolution you will still get a 80x24 terminal by default. Which is the whole purpose of `git log`. Using it on a terminal / ssh session / whatever.
- mamadrood 10y ago
  I use ~80 cols terminal because everything is designed to fit in 80 anyway. More than that and it's just whitespace.
raimue 10y ago
The reason for this is that Git patches are meant to be exchanged over email. Historically email has a line limitation of 80 characters. You are supposed to use less than that to allow insertion of quoting characters in the first columns in replies.
- marcosdumay 10y ago
  Your email client is supposed to fix this restriction in a completely transparent way. There are a few standards for that, and you can bet every client supports all of them.
  - raimue 10y ago
    Uhm, no, that is not the reality we live in. Things like format=flowed exist, but I would not say that "all" clients support that. For example Apple Mail lately got an obsession for quoted printable encoding with very long lines.

struppi 10y ago

Recently, I try to write the first line of my commit messages so they describe what the system now does, compared to before the commit. This makes reading the history much more fun. Like: Validation of email addresses now sends a test email to the user, instead of the old regex that never worked. This style does not work for all kinds of changes, but when it works, it creates a nice history of how the functionality of the system grew...

345678545678655 10y ago
Looks too long to me, will end up looking bad in most things.
TheDong 10y ago
Including the old bit is meaningless noise there. I'd use something like "Improve email validation" or "email: send a test email as validation" or such. The body is where you can describe previous behaviour and give more details.
- Cthulhu_ 10y ago
  Yeah that. I'd have it describe what the commit does in the subject, and both the why and how in the body: Validation of email addresses now sends a test email to the user, instead of the old regex that never worked. > Send test email to user for email address validation > > This change was done because the old regex never worked; see also {link} and {link} for more information. as an example. Ideally the header also contains a hint to the module the change was done in, etc. The linux kernel commits take this to (what comes across to me as) the highest levels.

fit2rule 10y ago

My commit messages are (usually) one-line, starting early in the sentence with the focus of the effort, and ending with a clear statement of what happened.

mojuba 10y ago

Should be noted, it is often tempting to describe everything about the change in the commit description rather than comments in the code. Remember, git commits disappear from sight pretty soon and become fossils, whereas there may be something important that should be said in the code itself.

karim 10y ago
I think that on the contrary, everything should be in the commit. The commit message is dated, it has an author and a context. How often do you come across stray comments which shouldn't be here because the code got refactored away? Commis are often just a git blame away anyway.
- Cthulhu_ 10y ago
  Except when a line has been changed over a longer period of time. Although maybe I'm just not comfortable with tracking history too much, because in the applications I generally work on (customer-facing webapps) we generally don't need to look back in history too much.
nailer 10y ago
Also: avoid using comments where proper names would suffice: // cleans responses function zrgfy(response){ ... } should be something like: function cleanResponse(response){ ... }
- chousuke 10y ago
  My rule of thumb in commenting is that I comment the why or how, not the what... Unless the what is sufficiently non-obvious, in which case it is usually prudent to have a really good explanation of the why, as well.
  - deleted 10y ago
    [deleted]
10y ago

dang 10y ago

Url changed from https://gist.github.com/matthewhudson/1475276 https://gist.github.com/matthewhudson/1475276, which (kind of) points to this.

chris_7 10y ago

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. Software should help me, I shouldn't have to help it. Why doesn't git handle this formatting automatically? I shouldn't need to manually break lines for typographical (not paragraph) reasons.

raimue 10y ago
That software is called a text editor and you can configure it to do the text wrapping for you. More seriously, it is quite hard to wrap text correctly after you submitted it. For example people add manual line breaks for structuring text and to separate things like quoted commands from the rest. It would be much more cumbersome to go back after a git commit to fix this, probably in multiple iterations until you get the intended presentation instead of just doing it right from the start.
- chris_7 10y ago
  Web browsers line break text dynamically just fine - as do, well, text editors. Using a text editor to automatically embed line breaks doesn't fix the problem: embedding line breaks in text for formatting is wrong semantically. Hard line breaks should mean something. Now I can't reflow the text to display it on a web page in a normal font, because I can't be sure of which line breaks are meaningful, and which are formatting.
  - masklinn 10y ago
    Except now you need everything to handle textual contexts because while I do want my nice paragraph of text to be wrapped, I don't want my code snippet to be wrapped at all, and I want my nested list to be correctly intended at wrapping.
    - chris_7 10y ago
      Is there not precedent for handling that correctly in a plain text field?

gempir 10y ago

Great system about our commit system at work is that every commit starts with the name of a ticket of our ticket system (jira) so you can go back to that ticket whenever that commit comes up anywhere and understand the commit better

superzadeh 10y ago
even better systems allows to link tickets to commits.
- gregmac 10y ago
  Not the OP, but our JIRA instance does this. From a ticket in JIRA, you can see any commits, branches or pull requests mentioning that ticket. We also use this convention with gitflow, so our branches are named eg, feature/PROJ-1234-added-new-ui or bug/PROJ-2345-fix-new-ui. This also lets JIRA find and link them, and makes pull requests get the ticket number in their title by default as well (since its based on branch name). The last bit is just a short human-readable thing to make branches easier to look at and find, because the initial way we started using gitflow: feature/ feature/PROJ-2286 feature/PROJ-2352 feature/PROJ-2367 feature/PROJ-2382 feature/PROJ-2385 bug/ bug/PROJ-2240 bug/PROJ-2323 bug/PROJ-2393 is completely unintelligible.

dallamaneni 10y ago

I made this git commit template sometime ago. Check it out if it is of any help: https://gist.github.com/adeekshith/cd4c95a064977cdc6c50 https://gist.github.com/adeekshith/cd4c95a064977cdc6c50

wruza 10y ago

Just for those who are tired of sites that disable both 2tap-zoom and 'pre' block wrapping on mobile. --- A good commit message looks like this: 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. Reported-by: whoever-reported-it Signed-off-by: Your Name <youremail@yourhost.com> where that header line really should be meaningful, and really should be just one line. That header line is what is shown by tools like gitk and shortlog, and should summarize the change in one readable line of text, independently of the longer explanation.

StapleHorse 10y ago

Relevant xkcd https://xkcd.com/1296 https://xkcd.com/1296 I once wrote "commit". A fellow coworker still makes fun of me for that, joking of course.

svckr 10y ago

Here's what, Tim Pope, our favourite vim nerd has to say about this: 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... (Same, but with more words.) A point of contention seems to be the choice of the imperative, at least for the subject line. While I'm really used to it, both when reading and writing, many people seem to strongly prefer past tense ("Fixed bug …" instead of "Fix bug …").

Cthulhu_ 10y ago
With that one, the way I see it is that when people use the past tense, the git history becomes a work log, i.e. what the committer did; "I fixed bug...". It shouldn't be like that, the commit should describe what the commit does, i.e. "Fix bug" or "Fixes bug". the latter uses more letters though, which is probably why I see a preference for the "Fix bug" format due to the (soft) 50 character subject constraint.
- gumby 10y ago
  I am wary of agreeing with someone with your uname but I have to agree! Go with the project's style, but best is if that style is about the code itself. I don't care if this was easy or hard or the bug was non-obvious or if you used a weird trick. I do care what the change does: fixes a race condition, adds a new file mode etc. Those changes matter at the time (what's new in the code?) and when looking backwards (ah, here's where that new file mode was added, let's see what was going on then).
Tarean 10y ago
Also, when using his amazing git plugin (fugitive) to commit you get very useful highlighting when you break these conventions. http://i.imgur.com/8ix5JGa.png http://i.imgur.com/8ix5JGa.png
gregmac 10y ago
More importantly, the correct way is the way that is currently being used. If the project uses past tense, use it. If you want to change the convention, that's okay too, but everyone has to change. It's exactly the same issue as coding style. If you can look at code or commit messages and figure out who wrote it based purely on style/formatting, you're doing it wrong (or rather: the person using the inconsistent style/format is).

collyw 10y ago

One problem with this is that git gets used as a deployment tool as well as a version control system. Trying to get something to run on Heroku involved making lots of small changes just to get things to run on the server the same as on my dev machine. When you do that 10 or 20 times the commit message become somewhat meaningless.

vinhboy 10y ago
I also commit like 20 things to get Heroku working properly. But after I am done with that, I `rebase` it into one commit. Then I push it into my `origin/master`, and force push `heroku/master`.
jtmarmon 10y ago
generally when I'm trying this stuff I'll make a new branch to work off of and deploy from that. when I've figured out how it needs to work, I'll squash the commits and merge into master.

msimpson 10y ago

The link within that README leading to what "Signed-off-by" means is now broken. Use: https://gerrit-review.googlesource.com/Documentation/user-signedoffby.html https://gerrit-review.googlesource.com/Documentation/user-si...

binarnosp 10y ago

I open an issue for every feature, bug or enhancement, then I mention the issue in the commit followed by a short description of the changes. I wrote down a procedure that I follow for every commit [1]. This allows me to keep the commit line short and to see the commits history related to the resolution of a bug or feature. When using Gitlab, Bitbucket or Github the issues and the commits are cross-linked (example: [0]). [0] https://bitbucket.org/binarno/imebra/issues/162/ https://bitbucket.org/binarno/imebra/issues/162/ [1] https://imebra.com/wp-content/uploads/documentation/html/sop.html#sop-fixbug-2-fixing-a-bug https://imebra.com/wp-content/uploads/documentation/html/sop...

leotartari 10y ago

This is still relevant, as my friend Cesar wrote about it just the other day (with a very similar title) » https://hackernoon.com/what-makes-a-good-commit-message-995d23687ad#.5sc2xvg92 https://hackernoon.com/what-makes-a-good-commit-message-995d...

__strisk 10y ago

don't use git commit messages as "dear diary" sort of things. For example: "I fixed the button issue on the homepage. Still, need to center the title." would be better written as: "fixes button issue on homepage" Always think about what that commit does to the codebase. This is obviously for single-line commits. I suppose it would be okay to "dear diary" in the commit body. You can provide rationality or context in the commit body.

wolfgang42 10y ago
My recommended style is: Fix button issue on homepage This allows the title to be centered, as the button will no longer collide with it. Then, in a subsequent commit, center the title and put a reference to this one if you feel it's important, like so: Center the title on the homepage It wasn't previously because it would collide with the button, but that was fixed in f00b1f.

jordansmithnz 10y ago

Nice. At an old job, I got a little bored, so I'd spend time crafting wonderful commit messages. Most of them contained puns, some very subtle, some less so. In regards to commit ethos, I'm not sure I agree with all of the statements made. To me, something simple/concise, that others will understand, but not lacking in key info, is much better than several paragraphs explaining the same thing.