6 ms·

Commit messages are whatever an individual, community, or organization decides they should be. Debating beyond that is like debating tabs vs spaces. It doesn't

Commit messages are whatever an individual, community, or organization decides they should be. Debating beyond that is like debating tabs vs spaces. It doesn't matter as long as everyone you're working with is on the same page.

flafla2 7y ago
I agree, context is everything. Some commenters here and in the OP argue that there should be no dot at the end because git commit messages are used as the subject of emails. This is of course true in the context of e.g. the linux kernel [1], so the advice makes sense in that context. But realistically most people today view git through a different client than email, usually github/git CLI. Often, commit messages are the same as PR titles; in that context it makes sense to adopt commits-as-titles. It all comes down to team preference ultimately. [1] Technically not 100% true these days due to the github mirror
ticmasta 7y ago
Step 1: pick a commit message format. Step 2: be a dick about it.
duxup 7y ago
Seriously, in an interview I was asked about some misc code formatting preferences. At home I use whatever prettier decides. At work I just want to do what everyone else is doing so that we are on the same page. Maybe it is weird or something, I really don't care. More important we all work together.
- Already__Taken 7y ago
  If AI can write news articles these days I wonder if the actual answer is what you wrote. Build a commit parser into version control to auto-write the titles for you. All you do is write a good message. Prettier but for commit messages.
  - pjc50 7y ago
    > Build a commit parser into version control to auto-write the titles for you. This is like the auto-javadoc software: if the computer can write it from information already in the code, it's a wasteful duplication of time. Use commit messages and comments for why. Especially if you chose not to do something in a more obvious way for a specific reason. You can't have "self-documenting" for code the version of code that wasn't written.
    - Already__Taken 7y ago
      The title is a duplication of effort from the message. Devs just write a good message, generate a perfect title from that and the context of the commit itself.
Lilian_Lee 7y ago
I agree that an organization should decide what commit message style they'll follow. Here is a commit message style guide as a reference: https://github.com/pingcap/community/blob/master/contributors/commit-message-pr-style.md https://github.com/pingcap/community/blob/master/contributor...
protonimitate 7y ago
The "rule" I like when it comes to commit messages it that they should be clear enough that someone who gets woken up for a production issue at 3am can quickly parse what was in the commit and how dangerous it is. Nothings worse than digging through a ton of diffs to find the breaking change.
- beatgammit 7y ago
  Yup. I follow the kernel commit message guide, since it seems pretty reasonable. It's basically: 1. really short summary in a few words, ideally mentioning the relevant issue(s) in the bug tracker 2. Blank line 3. Longer message, if necessary, to explain the change If I'm going to be looking back through commit messages, that's the type of commit message I want to read. I want to know whether this commit is interesting or if I can safely skip it. It doesn't need to be complicated. Just write a short note as if you wanted to remind yourself where you left off when you come back from vacation.
  - em-bee 7y ago
    another use for commit messages is to document learning. when we figured out how to avoid a certain type error in typescript, we made sure to describe it in a way that we would find it again, or it would come up in a search.
- bagacrap 7y ago
  yeah althouggh looking at touched files tends to be a heck of a lot more helpful IME especially if you have a stack trace
- lmm 7y ago
  I find that requiring "nice" commit messages tends to mean digging through bigger diffs to find the breaking change. If you're fine with commit messages like "fix" or "derp", then people are more willing to make each tiny change a separate commit, and then a git bisect takes you right to the specific diff that caused the problem.
  - 7y ago
alwillis 7y ago
I've found the semantic commit concept to be quite helpful: https://seesparkbox.com/foundry/semantic_commit_messages https://seesparkbox.com/foundry/semantic_commit_messages
jangid 7y ago
Agree. In one group, I have to put title (summary) in one line and that's it. In Emacs, we have a title in the first line and then bulleted (*) summary for each file in the changeset. See http://git.savannah.gnu.org/cgit/emacs.git/commit/ http://git.savannah.gnu.org/cgit/emacs.git/commit/. I prefer the later. But that is not always possible.
coldtea 7y ago
That's an easy copout though. Sure, commit messages could be mandated to be "whatever an individual, community, or organization decides they should be". That doesn't mean any of those choices is optimal in absolute terms, or even optimal for the use case of the individual, community, or organization who made the decision. So it makes sense then to debate what the optimal choice (either absolute, or per use case) is, and this is what the article tries to do. It would be even better if we had some kind of objective, statistical check on such claims and their pros/cons (e.g. a massive test, with control groups, well defined procedures, and such). But debating them is also a start, and is needed. If not for anything so that each "individual, community, or organisation" has some input on their decision, and don't just arbitrary impose a format for their commit messages.
- flafla2 7y ago
  I think the core issue is that people consume/view Git commit messages in different ways depending on their needs. Realistically, most people today use Github/Gitlab/Sourcehut/whatever web git gui along with the Git CLI. So the old wisdom of "commit-as-subjects," which made sense when people viewed commits in email chains, is no longer always relevant. In many organizations and communities, git commit messages mirror PR titles, and in this specific context it makes a lot of sense for commit messages to be written as titles with a longer description attached. As an individual, I might use git to version a blog post I'm writing, and in this case I could use my own entirely individualized semantics for commit messages. I don't even think there is a choice that is "optimal in absolute terms" as you claim. However, consistency within a project is absolutely key and is something we can hopefully all agree on.
  - coldtea 7y ago
    >Realistically, most people today use Github/Gitlab/Sourcehut/whatever web git gui along with the Git CLI. So the old wisdom of "commit-as-subjects," which made sense when people viewed commits in email chains, is no longer always relevant. It's not "commits as subjects", it's commits as titles. And it doesn't come from viewing the commits through email clients. It comes from needing to know what the commit contains and why was the change done. That is, from having a descriptive title for the change. This is needed whether one checks the commit in their email, on Emacs, on GitHub, or cli. >As an individual, I might use git to version a blog post I'm writing, and in this case I could use my own entirely individualized semantics for commit messages. Sure, that's a niche use though, not the use discussed here, which is about commit messages for programming.

flafla2 7y ago

I agree, context is everything. Some commenters here and in the OP argue that there should be no dot at the end because git commit messages are used as the subject of emails. This is of course true in the context of e.g. the linux kernel [1], so the advice makes sense in that context. But realistically most people today view git through a different client than email, usually github/git CLI. Often, commit messages are the same as PR titles; in that context it makes sense to adopt commits-as-titles. It all comes down to team preference ultimately. [1] Technically not 100% true these days due to the github mirror

ticmasta 7y ago

Step 1: pick a commit message format. Step 2: be a dick about it.

duxup 7y ago

Seriously, in an interview I was asked about some misc code formatting preferences. At home I use whatever prettier decides. At work I just want to do what everyone else is doing so that we are on the same page. Maybe it is weird or something, I really don't care. More important we all work together.

Already__Taken 7y ago
If AI can write news articles these days I wonder if the actual answer is what you wrote. Build a commit parser into version control to auto-write the titles for you. All you do is write a good message. Prettier but for commit messages.
- pjc50 7y ago
  > Build a commit parser into version control to auto-write the titles for you. This is like the auto-javadoc software: if the computer can write it from information already in the code, it's a wasteful duplication of time. Use commit messages and comments for why. Especially if you chose not to do something in a more obvious way for a specific reason. You can't have "self-documenting" for code the version of code that wasn't written.
  - Already__Taken 7y ago
    The title is a duplication of effort from the message. Devs just write a good message, generate a perfect title from that and the context of the commit itself.

Lilian_Lee 7y ago

I agree that an organization should decide what commit message style they'll follow. Here is a commit message style guide as a reference: https://github.com/pingcap/community/blob/master/contributors/commit-message-pr-style.md https://github.com/pingcap/community/blob/master/contributor...

protonimitate 7y ago

The "rule" I like when it comes to commit messages it that they should be clear enough that someone who gets woken up for a production issue at 3am can quickly parse what was in the commit and how dangerous it is. Nothings worse than digging through a ton of diffs to find the breaking change.

beatgammit 7y ago
Yup. I follow the kernel commit message guide, since it seems pretty reasonable. It's basically: 1. really short summary in a few words, ideally mentioning the relevant issue(s) in the bug tracker 2. Blank line 3. Longer message, if necessary, to explain the change If I'm going to be looking back through commit messages, that's the type of commit message I want to read. I want to know whether this commit is interesting or if I can safely skip it. It doesn't need to be complicated. Just write a short note as if you wanted to remind yourself where you left off when you come back from vacation.
- em-bee 7y ago
  another use for commit messages is to document learning. when we figured out how to avoid a certain type error in typescript, we made sure to describe it in a way that we would find it again, or it would come up in a search.
bagacrap 7y ago
yeah althouggh looking at touched files tends to be a heck of a lot more helpful IME especially if you have a stack trace
lmm 7y ago
I find that requiring "nice" commit messages tends to mean digging through bigger diffs to find the breaking change. If you're fine with commit messages like "fix" or "derp", then people are more willing to make each tiny change a separate commit, and then a git bisect takes you right to the specific diff that caused the problem.
- 7y ago

alwillis 7y ago

I've found the semantic commit concept to be quite helpful: https://seesparkbox.com/foundry/semantic_commit_messages https://seesparkbox.com/foundry/semantic_commit_messages

jangid 7y ago

Agree. In one group, I have to put title (summary) in one line and that's it. In Emacs, we have a title in the first line and then bulleted (*) summary for each file in the changeset. See http://git.savannah.gnu.org/cgit/emacs.git/commit/ http://git.savannah.gnu.org/cgit/emacs.git/commit/. I prefer the later. But that is not always possible.

coldtea 7y ago

That's an easy copout though. Sure, commit messages could be mandated to be "whatever an individual, community, or organization decides they should be". That doesn't mean any of those choices is optimal in absolute terms, or even optimal for the use case of the individual, community, or organization who made the decision. So it makes sense then to debate what the optimal choice (either absolute, or per use case) is, and this is what the article tries to do. It would be even better if we had some kind of objective, statistical check on such claims and their pros/cons (e.g. a massive test, with control groups, well defined procedures, and such). But debating them is also a start, and is needed. If not for anything so that each "individual, community, or organisation" has some input on their decision, and don't just arbitrary impose a format for their commit messages.

flafla2 7y ago
I think the core issue is that people consume/view Git commit messages in different ways depending on their needs. Realistically, most people today use Github/Gitlab/Sourcehut/whatever web git gui along with the Git CLI. So the old wisdom of "commit-as-subjects," which made sense when people viewed commits in email chains, is no longer always relevant. In many organizations and communities, git commit messages mirror PR titles, and in this specific context it makes a lot of sense for commit messages to be written as titles with a longer description attached. As an individual, I might use git to version a blog post I'm writing, and in this case I could use my own entirely individualized semantics for commit messages. I don't even think there is a choice that is "optimal in absolute terms" as you claim. However, consistency within a project is absolutely key and is something we can hopefully all agree on.
- coldtea 7y ago
  >Realistically, most people today use Github/Gitlab/Sourcehut/whatever web git gui along with the Git CLI. So the old wisdom of "commit-as-subjects," which made sense when people viewed commits in email chains, is no longer always relevant. It's not "commits as subjects", it's commits as titles. And it doesn't come from viewing the commits through email clients. It comes from needing to know what the commit contains and why was the change done. That is, from having a descriptive title for the change. This is needed whether one checks the commit in their email, on Emacs, on GitHub, or cli. >As an individual, I might use git to version a blog post I'm writing, and in this case I could use my own entirely individualized semantics for commit messages. Sure, that's a niche use though, not the use discussed here, which is about commit messages for programming.