6 ms·

It's instructive to read Linus's commits to his hobby project "subsurface": https://github.com/torvalds/subsurface/commits/master https://github.com/torvalds/s

by mjs 14y ago

It's instructive to read Linus's commits to his hobby project "subsurface": https://github.com/torvalds/subsurface/commits/master https://github.com/torvalds/subsurface/commits/master Even if I can't code like Linus, I can at least try to write commit messages like his…

why-el 14y ago
It always puzzled me why his commits (and in fact standard commits) ought to start with a verb that is not in its past form. When I started using git four months ago (such a newbie), I would write something like "Fixed this" instead of "Fix this". Anybody with more insights on this? I am just curious.
- purephase 14y ago
  It is part of the git best practices: http://git.kernel.org/?p=git/git.git;a=blob;f=Documentation/SubmittingPatches;h=ece3c77482b3ff006b973f1ed90b708e26556862;hb=HEAD http://git.kernel.org/?p=git/git.git;a=blob;f=Documentation/...
  - deleted 14y ago
    [deleted]
  - mjs 14y ago
    The HEAD version is a bit different (less clear?), although the intent is more or less the same: "describe changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behaviour." http://git.kernel.org/?p=git/git.git;a=blob;f=Documentation/SubmittingPatches;hb=HEAD http://git.kernel.org/?p=git/git.git;a=blob;f=Documentation/...
    - why-el 14y ago
      Exactly, same as when you are cherry-picking.
- freeman478 14y ago
  In my opinion its because your commit log should read like a novel and not like a history book. It's also simpler and promotes less convoluted phrasing.
  - philwelch 14y ago
    I haven't read many novels lately, but I always thought they were written in past tense.
- gchpaco 14y ago
  If you think of the change set as the subject, so the question is 'what does this do?' and the answer is 'fix X' then it makes more sense. Past tense suggests you might be thinking of it as a journal or something that you're not supposed to do with git due to rebase etc.; each commit ought to stand on its own. That said I don't think this is significant enough to add up to a compelling reason either way.
  - why-el 14y ago
    Your point about rebase is compelling enough for me. :) I thoroughly missed that. Thanks.
  - nirvdrum 14y ago
    Sorry, pardon the ignorance, but how does past tense imply something that would be affected by rebase? It may not be linear history, but it definitely happened in the past. I guess I always looked at more as: "here's a patch", "what did you do?" If it's just a tomato/tomato thing (yeah, that doesn't come out well in text), just let me know.
    - gchpaco 14y ago
      Because rebase, and rebase -i especially, gives you the ability to break your patches into discrete this-one-one-goddamn-thing patches (which is awkward in a "oh, you committed it? Then you committed it forever" SCM like Perforce or SVN), you should do so. It makes it a lot easier to review than the "so this does X, but also fixes some syntax errors and adds logging" style. And that means you should make the patch comment reflect what it is doing. Some errors here are inevitable but it's something to which I aspire. Edit: to be a little clearer; your traditional SCM has a write-once-never-change model for the trunk of development. This has a problem in a peer review situation, and the problem is this: I may go forth with the best of intentions to decompose things into discrete patches. But when you get down to brass tacks, changes to the system tend to happen in any given order--you might discover a latent bug when testing your feature that has nothing to do with your feature. Now you have two choices: you can wait and commit nothing until everything is great, which means you're not integrating with the mainline, which means that integrating will be incredibly painful, which leads to locks; or you commit as it comes in the moment, which is much better for integration and much easier to back out partial changes and generally get all of the non-backup elements of an SCM, but which is the very devil to peer review. With rebase -i, it is quite easy to commit in the second style in the moment and then clean them up for peer review later; that is the ability to revise history means you can make decisions immediately without worrying that they will be cast in stone forever and ever anon. I wasn't always this much of a hardliner on the subject, but my current job uses Perforce as the main SCM and I have realized that I disagree with almost every decision Perforce makes across the board. I still use it, because any SCM is way better than no SCM and I don't want to explain git to everyone else, but my actual development occurs with git-p4.
- deleted 14y ago
  [deleted]
- deleted 14y ago
  [deleted]
- rlpb 14y ago
  Whether your commit is historical or not depends on your point of view. Git is distributed. For whose repository is it historical? What if I pull out the commit using git format-patch? Is it still historical now?
- cleaver 14y ago
  I can think of a few reasons for the grammar rules in the commit message... It is direct, concise, consistent and tends to active voice rather than passive voice. Further, not everyone writing or reading the messages will be a native English speaker. Avoiding past-tense forms just makes it easier.
  - why-el 14y ago
    I am actually not a native English speaker and I always thought that this was hard to understand specifically because English is my first language. But again folks provided enough information for me to understand the reasons for it to be this way.
- dmethvin 14y ago
  See his other rant about Github's handling of single-line commit summaries. When space is at a premium it's a waste to past-tensify all the verbs since it inevitably wastes precious characters in the one-line description. It drives me nuts that I never know exactly when Github will break my one-line descriptions when there appears to be plenty of room left to display the characters. Like this one from Linus: https://github.com/torvalds/subsurface/commit/bea6637c03a90fbb9e754f5f63625fffb7cbaa69 https://github.com/torvalds/subsurface/commit/bea6637c03a90f...
- Aga 14y ago
  A commit can be seen as a changeset. A changeset can be formatted as a patch. Projects like Git and Linux take their contributions in as patches that are sent to the projects mailing list. As it is not merged in to the master tree at the time of publishing, it would not make sense to use past tense for describing what it should do, if merged. Thanks to Git's great history-graph altering functions like rebase and cherry-picking, it would make even less sense. You can always take some commit and apply it to new branches or even repositories.
- sage_joch 14y ago
  This is the first time I've seen his commits, but I do the same thing at work, deliberately. I don't pretend to know his reasons, but I've always had fun with the idea that if there were a super high-level language, it would look similar to a commit message and the corresponding changes would take place. And so I have changes that look like "Optimize the foo() function", etc.
  - cpeterso 14y ago
    I like the "super high-level language" perspective. I imagine commit history like a (journaling file system's) journal, whose commands can be undone and replayed.
- deleted 14y ago
  [deleted]
- drothlis 14y ago
  According to 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... (linked in one of the comments in the github discussion) it is for consistency with the commit message generated by 'git merge' and the like.

by mjs 14y ago

why-el 14y ago

It always puzzled me why his commits (and in fact standard commits) ought to start with a verb that is not in its past form. When I started using git four months ago (such a newbie), I would write something like "Fixed this" instead of "Fix this". Anybody with more insights on this? I am just curious.

purephase 14y ago
It is part of the git best practices: http://git.kernel.org/?p=git/git.git;a=blob;f=Documentation/SubmittingPatches;h=ece3c77482b3ff006b973f1ed90b708e26556862;hb=HEAD http://git.kernel.org/?p=git/git.git;a=blob;f=Documentation/...
- deleted 14y ago
  [deleted]
- mjs 14y ago
  The HEAD version is a bit different (less clear?), although the intent is more or less the same: "describe changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behaviour." http://git.kernel.org/?p=git/git.git;a=blob;f=Documentation/SubmittingPatches;hb=HEAD http://git.kernel.org/?p=git/git.git;a=blob;f=Documentation/...
  - why-el 14y ago
    Exactly, same as when you are cherry-picking.
freeman478 14y ago
In my opinion its because your commit log should read like a novel and not like a history book. It's also simpler and promotes less convoluted phrasing.
- philwelch 14y ago
  I haven't read many novels lately, but I always thought they were written in past tense.
gchpaco 14y ago
If you think of the change set as the subject, so the question is 'what does this do?' and the answer is 'fix X' then it makes more sense. Past tense suggests you might be thinking of it as a journal or something that you're not supposed to do with git due to rebase etc.; each commit ought to stand on its own. That said I don't think this is significant enough to add up to a compelling reason either way.
- why-el 14y ago
  Your point about rebase is compelling enough for me. :) I thoroughly missed that. Thanks.
- nirvdrum 14y ago
  Sorry, pardon the ignorance, but how does past tense imply something that would be affected by rebase? It may not be linear history, but it definitely happened in the past. I guess I always looked at more as: "here's a patch", "what did you do?" If it's just a tomato/tomato thing (yeah, that doesn't come out well in text), just let me know.
  - gchpaco 14y ago
    Because rebase, and rebase -i especially, gives you the ability to break your patches into discrete this-one-one-goddamn-thing patches (which is awkward in a "oh, you committed it? Then you committed it forever" SCM like Perforce or SVN), you should do so. It makes it a lot easier to review than the "so this does X, but also fixes some syntax errors and adds logging" style. And that means you should make the patch comment reflect what it is doing. Some errors here are inevitable but it's something to which I aspire. Edit: to be a little clearer; your traditional SCM has a write-once-never-change model for the trunk of development. This has a problem in a peer review situation, and the problem is this: I may go forth with the best of intentions to decompose things into discrete patches. But when you get down to brass tacks, changes to the system tend to happen in any given order--you might discover a latent bug when testing your feature that has nothing to do with your feature. Now you have two choices: you can wait and commit nothing until everything is great, which means you're not integrating with the mainline, which means that integrating will be incredibly painful, which leads to locks; or you commit as it comes in the moment, which is much better for integration and much easier to back out partial changes and generally get all of the non-backup elements of an SCM, but which is the very devil to peer review. With rebase -i, it is quite easy to commit in the second style in the moment and then clean them up for peer review later; that is the ability to revise history means you can make decisions immediately without worrying that they will be cast in stone forever and ever anon. I wasn't always this much of a hardliner on the subject, but my current job uses Perforce as the main SCM and I have realized that I disagree with almost every decision Perforce makes across the board. I still use it, because any SCM is way better than no SCM and I don't want to explain git to everyone else, but my actual development occurs with git-p4.
deleted 14y ago
[deleted]
deleted 14y ago
[deleted]
rlpb 14y ago
Whether your commit is historical or not depends on your point of view. Git is distributed. For whose repository is it historical? What if I pull out the commit using git format-patch? Is it still historical now?
cleaver 14y ago
I can think of a few reasons for the grammar rules in the commit message... It is direct, concise, consistent and tends to active voice rather than passive voice. Further, not everyone writing or reading the messages will be a native English speaker. Avoiding past-tense forms just makes it easier.
- why-el 14y ago
  I am actually not a native English speaker and I always thought that this was hard to understand specifically because English is my first language. But again folks provided enough information for me to understand the reasons for it to be this way.
dmethvin 14y ago
See his other rant about Github's handling of single-line commit summaries. When space is at a premium it's a waste to past-tensify all the verbs since it inevitably wastes precious characters in the one-line description. It drives me nuts that I never know exactly when Github will break my one-line descriptions when there appears to be plenty of room left to display the characters. Like this one from Linus: https://github.com/torvalds/subsurface/commit/bea6637c03a90fbb9e754f5f63625fffb7cbaa69 https://github.com/torvalds/subsurface/commit/bea6637c03a90f...
Aga 14y ago
A commit can be seen as a changeset. A changeset can be formatted as a patch. Projects like Git and Linux take their contributions in as patches that are sent to the projects mailing list. As it is not merged in to the master tree at the time of publishing, it would not make sense to use past tense for describing what it should do, if merged. Thanks to Git's great history-graph altering functions like rebase and cherry-picking, it would make even less sense. You can always take some commit and apply it to new branches or even repositories.
sage_joch 14y ago
This is the first time I've seen his commits, but I do the same thing at work, deliberately. I don't pretend to know his reasons, but I've always had fun with the idea that if there were a super high-level language, it would look similar to a commit message and the corresponding changes would take place. And so I have changes that look like "Optimize the foo() function", etc.
- cpeterso 14y ago
  I like the "super high-level language" perspective. I imagine commit history like a (journaling file system's) journal, whose commands can be undone and replayed.
deleted 14y ago
[deleted]
drothlis 14y ago
According to 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... (linked in one of the comments in the github discussion) it is for consistency with the commit message generated by 'git merge' and the like.