7 ms·

Commit messages are not titles (2015)

xwdv 7y ago
Commit messages are not titles, or subjects, they are COMMANDS, written in the present tense, that describe exactly what will be done to the codebase if you merge in the commit. That’s pretty much all there is to say about it.
- ticmasta 7y ago
  Well, I'll say more... They are a summary of what will happen if the commit (which is a bunch of commands) is applied. They also can elaborate on the context around the commit. It's thoughtful of the commiter if your coworkers don't need to dive into the detailed changes to get a broad picture of why the commit exists.
  - brian_cunnie 7y ago
    This. Also, commit messages are sometimes the "documentation of last resort". In my organization, putting comments in the code is frowned upon. "Comments are lies! The documentation is in the tests!" But the tests don't lend themselves to _reasons_ behind why the code was written a certain way, why a given approach was taken (for example, we needed to re-write a Rails database migration in a somewhat contorted manner to avoid a deadlock that was occurring in production). In such organizations, the git commit message are often the best place to warn future programmers of pitfalls: "don't even think of parallelizing these table updates—you'll get deadlocks!" [edited for brevity]
    - brigandish 7y ago
      The why is the thing most often missing from documentation of any sort. I often find myself looking at the README for a library I've not heard of and wondering what it will do for me because it only states the what, the why often tells me the/a problem the library solves. > Foobar packs JSON into binary vs > Our Rest API was slow and bandwidth heavy, so we wrote a library (Foobar) that packs JSON into a binary format. Now our messages are 50% smaller and 30% faster. Git commit messages are worse offenders but there's plenty of criminals about!
mcguire 7y ago
The first comment: "Every source control management system has its own rules. So what I say here for Git might not be valid for Mercurial, SVN, Bazaar, ... "Git has a wonderful tool named format-patch, http://git-scm.com/docs/git... http://git-scm.com/docs/git..., that takes a commit and converts it to an email, to put it in a nutshell. Why is there a tool for that? Because Git was created to manage Linux kernel development, and that is done in most parts in or around the Linux Kernel Mailing List. So, the entanglement between commits and emails is deep rooted in Git. And yes, the first line of the commit message _is_ used as the subject. "This explains, why you can google "git commit message" and find the same advice over and over again: "http://git-scm.com/docs/git...* http://git-scm.com/docs/git...* "https://github.com/erlang/o...* https://github.com/erlang/o...* "http://tbaggery.com/2008/04...* http://tbaggery.com/2008/04...* ""No dot at the end, because it might end up as email subject, also use 50 chars or less."* "I agree, that interpreting it as title for a longer commit message is a bad idea. The conciseness of this line is something important to be retained. A well-crafted email subject on the other hand makes in some cases reading the whole email unnecessary or only complimentary. (Yes, such things exist.) And that are the types of commit messages that we should strive for, ending with a dot or not."
caseymarquis 7y ago
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.
awolf 7y ago
> If the first line of a commit message is a title, it changes the way you write it. It becomes just some text to introduce some more text, without any stress on the information density. I agree with the author that commit messages should optimize for information density. However the example they provide does a poor job of this: > This is a smart synopsis, as information dense as possible. "This is a" is the type of thing that should never appear in a commit message as it could apply to EVERY commit message. Synopsizing is the action, but doesn't indicate what is being synopsized; one of the most important facts for someone to understand what is happening here. Finally "as information dense as possible", again should also be cut as this is telling us HOW not WHAT (and ironically hurts information density). Were I writing this example it would be: Synopsize how to write a commit message --- I led an initiative at my current company to enforce all commit messages start with an imperative verb and be less than 72 characters. Some people hate it, some people love it. Aside from standardization, the primary reason to do this is the imperative mood leads to the most concise sentence possible. By leading with the action, the most natural thing to do next is to talk about what is being acted upon. Unnecessary words are dropped and the most important facts are emphasized. In short it forces the author to get to the point. [Act] upon [some aspect of the code] e.g. Add user login link on home screen Refactor authentication into separate classes Lint PR titles conform to standard format
- schrodinger 7y ago
  > I led an initiative at my current company to enforce all commit messages start with an imperative verb and be less than 72 characters. You are truly doing god’s work :). I’ve led a similar initiative and same outcome, some love, but those who don’t, really hate it.
  - heavenlyblue 7y ago
    Why do they hate it? Are those the creative ones that can’t conform?
- singlow 7y ago
  I agree with your idea but I would take it further. If possible I think the commit message is more concise if it can actually refer to the resulting action that is the result of the change to the code, unless the primary result of the commit is to refactor or clean up code formatting, etc. This way we avoid one more level of indirection to indicate that we edited code to accomplish something, since that is always the case. Link to login from home screen Enforce standard for PR titles For refactoring, applying linting changes, or general formatting, I do prefer a prefix to indicate that it is not intended to change behavior. Something that is consistent for a project is good such as "Refactor:" or "Reformat:" or "Lint:" as a prefix to make it easy to spot these in the history is good. I often see message such as: Implemented new framework to... Edited 3 files... Then someone will edit it to be imperative and it reads: Implement new framework to... Edit 3 files... Which is not really any better. They were past tense indicative because they described the actions of the programmer which are in the past. Writing from the imperative is not just better because it is more concise in english (shorter verbs) but because it is the natural way to describe what will happen in the program when the commit is merged.
dang 7y ago
Discussed at the time: https://news.ycombinator.com/item?id=9763463 https://news.ycombinator.com/item?id=9763463
mc3 7y ago
Just use {JIRA Reference} - {JIRA title} and get on with your life.
- seattle_spring 7y ago
  The irony of this comment being that managing JIRA tickets is probably the absolute biggest time-sink of any organization that uses it.
  - other_herbert 7y ago
    Thankfully (and also regrettably) in the org I work in now we don't have a pr standard yet... But we do use jira some of our people commit with just the bug prefix and number and not at least the title.. I really don't want to have to go paste that into the jira URL (usually more than one) to see if what you think is the issue is really the issue... Having at least the description for what you fixed helps... Maybe it's time to dust off the "go to hell hat" and start demanding more info from the submitter...
  - Supermancho 7y ago
    The complexity context has to end up somewhere (or nowhere). JIRA is a superior tool in comparison to commit message text.
    - seattle_spring 7y ago
      And an industrial mining dump truck with 14 ft wheels is a superior tool to a cargo bicycle. Doesn't mean it's the right tool for the job.
  - mc3 7y ago
    I find JIRA light weight. The trick is not to follow too many processes. Drag on tickets to your board when you start them and move then through the swim lanes. The worst cases are when people set up too much security and complex transition rules so that people are blocked by JIRA. JIRA ain't perfect though. The constant UX changes drive me nuts. At least HN still works the same way as 10 years ago, but JIRA keeps changing like a shapeshifter.
thrower123 7y ago
Most commit messages look like this: #1234 fixed the fucking fooinater that wouldn't frobulate. Thank god for the hash ticket number linking standard. Unless you are working on the kernel, your context and discussions and notes are in the bugtracker, so there's no very good reason to write an essay in the commit log.
- reificator 7y ago
  Until you switch bug trackers and the import process subtly mangles that link, and then you switch trackers a few years later and all hope is lost, and then five years after that you hire someone to fix all the bugs that you've been accumulating and they can't tell any of the reasoning behind anything you've done. Are you always going to be on Jira? On Github? When people fork your project are they expected to clone your issues as well? When you migrate to another system are all your issue references still going to line up correctly? Did you even think to check? Please continue to include the ticket reference. But also put some context in your commit message because that's what it's there for. This is the same reason that even if you use a fancy documentation site, it should be generated from files in the repo.
  - bagacrap 7y ago
    Broadly speaking, so much documentation is on the issue tracker, that yes, I expect efforts to be made to preserve that content in perpetuity in one way or another.
sovietcattle 7y ago
Trying to impose "one way" to write commit messages is silly at best. At work I follow whatever convention the team I'm on agrees with. For my projects I use commit messages as a way to "tag" changes, more than to explain the changes using prose. That way it's very easy for me to search for changes in the codebase. eg. #event-loop #fix #multiple-dispatch #repeated-message (remove the # and you get the idea)
mceachen 7y ago
Capturing the reason why something was changed, why this approach was chosen, and possibly enumerating other approaches not taken (and why they weren't picked), are all gold to the Engineers of Tomorrow spelunking into some codebase. Summarizing a diff frequently doesn't add information that the diff itself already includes. Title or no title. I'm surprised we don't think about how to shout into the future more effectively. It might be ourselves that we're helping the most.
- kzzzznot 7y ago
  I think capTuring the “why” of a commit is often overlooked but highly valuable.
st_goliath 7y ago
There is probably no reasonable, generic guide on how to write commit messages, since different communities use git in different ways. So IMO this article is comparable to a discussion about indentation styles or text editors. > Commit messages are not titles > Nor subjects, for what matters. > ... > however many times there is no body, there is just the first line. In Linux (the Kernel) development (where git actually came from), commits are sent as patches via e-mail to mailing list for review and for maintainers to pick them up. The first line from the commit message becomes the subject line, the rest of the commit message and the diff becomes the body of the mail. The commit message should briefly explain why you are doing this, the what should be mostly in the diff itself. Having no body text after the first line for a non-trivial patch would be rather bad practice. Obviously the author of this article comes from a different background. But then again, in different communities, a concise single line description with a ticket number may be enough.
boomka 7y ago
Best practice advice used to be "dont leave your commit message empty" and now it seems headed in a direction of some kind of storytelling guide. Up next: the role of character development in your commit messages
- gpderetta 7y ago
  Show, don't tell!
gumby 7y ago
Why should a message subject not end with a period?

xwdv 7y ago

Commit messages are not titles, or subjects, they are COMMANDS, written in the present tense, that describe exactly what will be done to the codebase if you merge in the commit. That’s pretty much all there is to say about it.

ticmasta 7y ago
Well, I'll say more... They are a summary of what will happen if the commit (which is a bunch of commands) is applied. They also can elaborate on the context around the commit. It's thoughtful of the commiter if your coworkers don't need to dive into the detailed changes to get a broad picture of why the commit exists.
- brian_cunnie 7y ago
  This. Also, commit messages are sometimes the "documentation of last resort". In my organization, putting comments in the code is frowned upon. "Comments are lies! The documentation is in the tests!" But the tests don't lend themselves to _reasons_ behind why the code was written a certain way, why a given approach was taken (for example, we needed to re-write a Rails database migration in a somewhat contorted manner to avoid a deadlock that was occurring in production). In such organizations, the git commit message are often the best place to warn future programmers of pitfalls: "don't even think of parallelizing these table updates—you'll get deadlocks!" [edited for brevity]
  - brigandish 7y ago
    The why is the thing most often missing from documentation of any sort. I often find myself looking at the README for a library I've not heard of and wondering what it will do for me because it only states the what, the why often tells me the/a problem the library solves. > Foobar packs JSON into binary vs > Our Rest API was slow and bandwidth heavy, so we wrote a library (Foobar) that packs JSON into a binary format. Now our messages are 50% smaller and 30% faster. Git commit messages are worse offenders but there's plenty of criminals about!

mcguire 7y ago

The first comment: "Every source control management system has its own rules. So what I say here for Git might not be valid for Mercurial, SVN, Bazaar, ... "Git has a wonderful tool named format-patch, http://git-scm.com/docs/git... http://git-scm.com/docs/git..., that takes a commit and converts it to an email, to put it in a nutshell. Why is there a tool for that? Because Git was created to manage Linux kernel development, and that is done in most parts in or around the Linux Kernel Mailing List. So, the entanglement between commits and emails is deep rooted in Git. And yes, the first line of the commit message _is_ used as the subject. "This explains, why you can google "git commit message" and find the same advice over and over again: "http://git-scm.com/docs/git...* http://git-scm.com/docs/git...* "https://github.com/erlang/o...* https://github.com/erlang/o...* "http://tbaggery.com/2008/04...* http://tbaggery.com/2008/04...* ""No dot at the end, because it might end up as email subject, also use 50 chars or less."* "I agree, that interpreting it as title for a longer commit message is a bad idea. The conciseness of this line is something important to be retained. A well-crafted email subject on the other hand makes in some cases reading the whole email unnecessary or only complimentary. (Yes, such things exist.) And that are the types of commit messages that we should strive for, ending with a dot or not."

caseymarquis 7y ago

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.

awolf 7y ago

> If the first line of a commit message is a title, it changes the way you write it. It becomes just some text to introduce some more text, without any stress on the information density. I agree with the author that commit messages should optimize for information density. However the example they provide does a poor job of this: > This is a smart synopsis, as information dense as possible. "This is a" is the type of thing that should never appear in a commit message as it could apply to EVERY commit message. Synopsizing is the action, but doesn't indicate what is being synopsized; one of the most important facts for someone to understand what is happening here. Finally "as information dense as possible", again should also be cut as this is telling us HOW not WHAT (and ironically hurts information density). Were I writing this example it would be: Synopsize how to write a commit message --- I led an initiative at my current company to enforce all commit messages start with an imperative verb and be less than 72 characters. Some people hate it, some people love it. Aside from standardization, the primary reason to do this is the imperative mood leads to the most concise sentence possible. By leading with the action, the most natural thing to do next is to talk about what is being acted upon. Unnecessary words are dropped and the most important facts are emphasized. In short it forces the author to get to the point. [Act] upon [some aspect of the code] e.g. Add user login link on home screen Refactor authentication into separate classes Lint PR titles conform to standard format

schrodinger 7y ago
> I led an initiative at my current company to enforce all commit messages start with an imperative verb and be less than 72 characters. You are truly doing god’s work :). I’ve led a similar initiative and same outcome, some love, but those who don’t, really hate it.
- heavenlyblue 7y ago
  Why do they hate it? Are those the creative ones that can’t conform?
singlow 7y ago
I agree with your idea but I would take it further. If possible I think the commit message is more concise if it can actually refer to the resulting action that is the result of the change to the code, unless the primary result of the commit is to refactor or clean up code formatting, etc. This way we avoid one more level of indirection to indicate that we edited code to accomplish something, since that is always the case. Link to login from home screen Enforce standard for PR titles For refactoring, applying linting changes, or general formatting, I do prefer a prefix to indicate that it is not intended to change behavior. Something that is consistent for a project is good such as "Refactor:" or "Reformat:" or "Lint:" as a prefix to make it easy to spot these in the history is good. I often see message such as: Implemented new framework to... Edited 3 files... Then someone will edit it to be imperative and it reads: Implement new framework to... Edit 3 files... Which is not really any better. They were past tense indicative because they described the actions of the programmer which are in the past. Writing from the imperative is not just better because it is more concise in english (shorter verbs) but because it is the natural way to describe what will happen in the program when the commit is merged.

dang 7y ago

Discussed at the time: https://news.ycombinator.com/item?id=9763463 https://news.ycombinator.com/item?id=9763463

mc3 7y ago

Just use {JIRA Reference} - {JIRA title} and get on with your life.

seattle_spring 7y ago
The irony of this comment being that managing JIRA tickets is probably the absolute biggest time-sink of any organization that uses it.
- other_herbert 7y ago
  Thankfully (and also regrettably) in the org I work in now we don't have a pr standard yet... But we do use jira some of our people commit with just the bug prefix and number and not at least the title.. I really don't want to have to go paste that into the jira URL (usually more than one) to see if what you think is the issue is really the issue... Having at least the description for what you fixed helps... Maybe it's time to dust off the "go to hell hat" and start demanding more info from the submitter...
- Supermancho 7y ago
  The complexity context has to end up somewhere (or nowhere). JIRA is a superior tool in comparison to commit message text.
  - seattle_spring 7y ago
    And an industrial mining dump truck with 14 ft wheels is a superior tool to a cargo bicycle. Doesn't mean it's the right tool for the job.
- mc3 7y ago
  I find JIRA light weight. The trick is not to follow too many processes. Drag on tickets to your board when you start them and move then through the swim lanes. The worst cases are when people set up too much security and complex transition rules so that people are blocked by JIRA. JIRA ain't perfect though. The constant UX changes drive me nuts. At least HN still works the same way as 10 years ago, but JIRA keeps changing like a shapeshifter.

thrower123 7y ago

Most commit messages look like this: #1234 fixed the fucking fooinater that wouldn't frobulate. Thank god for the hash ticket number linking standard. Unless you are working on the kernel, your context and discussions and notes are in the bugtracker, so there's no very good reason to write an essay in the commit log.

reificator 7y ago
Until you switch bug trackers and the import process subtly mangles that link, and then you switch trackers a few years later and all hope is lost, and then five years after that you hire someone to fix all the bugs that you've been accumulating and they can't tell any of the reasoning behind anything you've done. Are you always going to be on Jira? On Github? When people fork your project are they expected to clone your issues as well? When you migrate to another system are all your issue references still going to line up correctly? Did you even think to check? Please continue to include the ticket reference. But also put some context in your commit message because that's what it's there for. This is the same reason that even if you use a fancy documentation site, it should be generated from files in the repo.
- bagacrap 7y ago
  Broadly speaking, so much documentation is on the issue tracker, that yes, I expect efforts to be made to preserve that content in perpetuity in one way or another.

sovietcattle 7y ago

Trying to impose "one way" to write commit messages is silly at best. At work I follow whatever convention the team I'm on agrees with. For my projects I use commit messages as a way to "tag" changes, more than to explain the changes using prose. That way it's very easy for me to search for changes in the codebase. eg. #event-loop #fix #multiple-dispatch #repeated-message (remove the # and you get the idea)

mceachen 7y ago

Capturing the reason why something was changed, why this approach was chosen, and possibly enumerating other approaches not taken (and why they weren't picked), are all gold to the Engineers of Tomorrow spelunking into some codebase. Summarizing a diff frequently doesn't add information that the diff itself already includes. Title or no title. I'm surprised we don't think about how to shout into the future more effectively. It might be ourselves that we're helping the most.

kzzzznot 7y ago
I think capTuring the “why” of a commit is often overlooked but highly valuable.

st_goliath 7y ago

There is probably no reasonable, generic guide on how to write commit messages, since different communities use git in different ways. So IMO this article is comparable to a discussion about indentation styles or text editors. > Commit messages are not titles > Nor subjects, for what matters. > ... > however many times there is no body, there is just the first line. In Linux (the Kernel) development (where git actually came from), commits are sent as patches via e-mail to mailing list for review and for maintainers to pick them up. The first line from the commit message becomes the subject line, the rest of the commit message and the diff becomes the body of the mail. The commit message should briefly explain why you are doing this, the what should be mostly in the diff itself. Having no body text after the first line for a non-trivial patch would be rather bad practice. Obviously the author of this article comes from a different background. But then again, in different communities, a concise single line description with a ticket number may be enough.

boomka 7y ago

Best practice advice used to be "dont leave your commit message empty" and now it seems headed in a direction of some kind of storytelling guide. Up next: the role of character development in your commit messages

gpderetta 7y ago
Show, don't tell!

gumby 7y ago

Why should a message subject not end with a period?