9 ms·

How to write good Git commit messages

47 points by ashitlerferad 6y ago

tobyhinloopen 6y ago
I approve this message
nikivi 6y ago
My recent preferred workflow is to automate commits for docs + commits inside feature branches with a tool I wrote (https://github.com/nikitavoloboev/gitupdate https://github.com/nikitavoloboev/gitupdate). It creates commits with the files changed as commit messages. The branches ideally gets squashed with proper commit message when merging so git history is clean. And no time is wasted writing commit messages that often say whatever the code should already say.
- explodingcamera 6y ago
  This seems like a really bad idea. Even a 2 word commit message would be better for someone who is trying to review your code, all git hosting websites include files changed anyways and it's trival to use the cli to check for that.
- naavis 6y ago
  In my experience commit messages shouldn't describe what was changed, they should describe why the change was made.
  - nikivi 6y ago
    that is why you shouldn't waste time writing commit messages for where this not much to `why` something has changed. (i.e. docs, refactors..)
    - bithaze 6y ago
      It's really not that much time though. "templates" and ".github" are examples of such vague commit messages that they _require_ looking at the commit to understand what changed. With a short, descriptive commit message, you can just glance through the commit log.
glxxyz 6y ago
I provided extended support on a custom system for about a year at a former employer, where the whole dev team had left before I started. I once tracked a bug down to a confusing line of code that looked like it shouldn't be there. Removing this line fixed the bug. When I looked in the commit history, that line was added as the only change in a commit that had no comment. I never worked out what they intended, e.g. whether it was a fix for something else I hadn't considered. In fact, and this is probably hard to believe, I don't think there were any comments anywhere in the commit history. Fun times.
lukevp 6y ago
I prefer commit messages to be of the form #issueid - summary of issue - additional details - more details Without a blank line anywhere. This makes it really easy to review in graphical git clients because the hyphens collapse into a single line like this: #issueid - summary of issue - additional details - more details Putting a blank line makes this rollup not happen.
IE6 6y ago
Another good resource I always point my developers to: https://chris.beams.io/posts/git-commit/ https://chris.beams.io/posts/git-commit/ As someone who manages many codebases this combined with thoughtful squashed commits allows me to (1) understand at a high level what each commit does, (2) drill into each commit should I choose to in order to review what was done in more detail, and (3) review a JIRA ticket relevant to the change (which often times is more valuable than 1 and 2).
- dchess 6y ago
  I was reminded of this resource as well since it is likewise what I use in training folks to use git. This OPs post seems to be a condensed version of Chris's advice.
kentosi 6y ago
For anyone questioning the imperative mood ("Add module x" as opposed to "Added module x"), what helps me it to think of each commit as a patch being applied. When I think of a patch it's almost always a patch that will "do the thing" rather than "did the thing".
bredren 6y ago
I’m nearing completion of a three month solo project where I used this style of commits, using it as an opportunity to practice doing this right. Along the way I looked at some plugins for Pycharm and came across this commit templating plugin that adds easy workflow for adding scope and commit type. https://plugins.jetbrains.com/plugin/9861-git-commit-template https://plugins.jetbrains.com/plugin/9861-git-commit-templat... Does anyone use commit message templating or style like this?
ravedave5 6y ago
Adding "why" to the message isn't even mentioned. Which is better: Updating the foobar threshold Updating the foobar threshold to improve performance.
- williamdclt 6y ago
  The why traditionally goes into the body of the commit message
Vinnl 6y ago
Maybe just as important: make sure the changes in a commit are related. `git blame` is a criminally underused feature, possibly because the benefits only become clear after you've had the discipline of paying attention to what goes in a commit. However, being able to pull up the context of related code right from the context of the line you're looking at [1] (from my post at [2]) can be very valuable. [1] https://vincenttunru.com/img/Commits-are-documentation/annotations.png https://vincenttunru.com/img/Commits-are-documentation/annot... [2] https://vincenttunru.com/Spend-effort-on-your-Git-commits/ https://vincenttunru.com/Spend-effort-on-your-Git-commits/
- ericol 6y ago
  I'm totally, utterly in love with Github's "Show blame previous to this commit" feature.
- graton 6y ago
  Many text editors now have this feature built in. Myself I use vim and the vim-fugitive plugin. Being able to do ":Gblame" is amazing. And then being able to step back in time to see what the code looked like before this commit is great too.
swanson 6y ago
I've worked for 10 years across 20 different commercial codebases. None of this stuff about writing good commit messages really matters. No one reads old commits. The "truth" is what the current code is doing and it doesn't really matter how it got there. I'm sure someone will say "but I use the history ALL THE TIME to source dive and paragraphs of context are super helpful". This is not the case for 95% of developers or projects so I can't really endorse spending time learning this "best practice". It's fine to be aspirational, but it's such a shame if people see posts like this and think they are failures or "bad" developers or that this is a widespread practice. If it helps you personally or you have an open source project and you want to help with a changelog, knock yourself out. But there are so many more impactful skills to be learning or spending your time on if you're a working developer in a typical environment.
- knappe 6y ago
  I can't disagree with this more. Good commit messages are just so, so, so important. Especially when I'm triaging an issue and have no other context than the code itself. I want to know not the _what_ which the code gives me, but also the _why_ which is what the commit message provides.
  - phailhaus 6y ago
    The why should not be in your source control, the why should be in comments in the code itself. There are many reasons why a line of code may have changed, and it's unreasonable to hide important contextual information in a commit and ask engineers to waste time digging through the commit history to find the initial change (which may have been in another file!).
    - deleted 6y ago
      [deleted]
    - wcarss 6y ago
      Comments almost always become lies with time, because code changes and nothing enforces that they are correct. Having commentary built into the artifact that introduced the change ensures your commentary applies to the specific change introduced. It's then possible to tell why someone did a specific thing, and also to tell how things are today, and to decide if that justification still applies, or if things no longer match the description. If you dig around a little bit, using e.g. the git pickaxe (-S), or github's excellent blame browsing tools, it's not that time consuming and you might find out some pretty surprising things.
ed25519FUUU 6y ago
I think there's a serious problem with people bikeshedding git. To squash or not squash, the types of commits, the messages in them, etc, etc ad nuasuem. I just want to easily be able to roll your changes back if there's a problem. That's all. With good tests, git bisect will find the issue regardless of how fancy and well written your commit messages are, or how squashed or un-squashed your commits are.
- joshmarlow 6y ago
  I see where you're coming from, but I would disagree on one thing - I always thought squashing wasn't that important until I tried to use `git bisect` in a project and found that a sizeable number of WIP commits didn't build (basically had to abandon using bisect). So I think there's a tooling reason for squashing - more effective use of `git bisect`.
nogabebop23 6y ago
I promoted something similar to all teams at my company (I'm a manager of one) and something that I thought was a no-brainer, common sense, easy win was met with very strong resistance - and mine was even more basic than these recommendations! It's great to recommend and we should keep coaching and mentoring but ultimately this is an area where I think you'd be better to go up the chain of command until you reach a benevolent dictator who can mandate criteria. I'd love to convince people based on the merits alone, but to paraphrase a common observation in academia "the resistance is high because the stakes are so low".
ericol 6y ago
I'm the half part of a 2 dev team. Last year it took me around 3 months of internal discussions between us devs and the project manager to get us to use a PR template in Github (The PM was more or less sold on the idea). Commit messages (Not mine, obviously) rarely amount to more than "Fixed <this>". And don't get me started on code comments (Non-existent, obviously). The other coder is responsible for around 90% of the new code we ship these days (The product is "frozen" because there is a better product developed by a different and larger team, but we still have clients on this one) and I also had to strong arm him into adding type hints for vars and functions (In PHP) because he is very fond of patterns (Think, SomeObjectFactoryFactoryFactory) so it would make development with PhpStorm easier. So now the code is polluted with /** * var $sometint integer */ that explain absolutely nothing.
ashton314 6y ago
When writing the subject line for a commit, I like to imagine myself explaining what I'm doing to a coworker, and I start off by saying, "applying this commit will…" and then type whatever comes after that. This explains the imperative tense. (Wait… is imperative a mood or a tense?)
graton 6y ago
An important thing for me in a commit message is the "why" of the commit. Sure it can state "changed foo to use blah". But why did they do that is often very important information. Sometimes it is very obvious from the what, but oftentimes it is not. The article didn't seem to mention this, or if it did I didn't notice it. I usually think a commit message should have a "what" changed and a "why" it changed portion. Of course putting this information in code comments may also be a wise thing to do.
mrspeaker 6y ago
How is "Do not end subject with a full stop" self-explanatory, but "Begin subject with a capital letter" not self-explanatory? Makes me suspect the author doesn't really know why they don't put a full stop ;) Now I don't know why don't you put one! I vaguely to remember reading this on the last "how to write good commit messages" blog and thinking it seemed fair, but now I can't think of a reason. Why follow grammar rules for the start of a sentence, but not the end?
- rement 6y ago
  Would you add a full stop in an email subject? I think of commit messages like an email. The first line is just the subject and sometimes that is all you need. The body of the commit message is for describing other details. edit: Another blog has a simple reason https://chris.beams.io/posts/git-commit/ https://chris.beams.io/posts/git-commit/ > 4. Do not end the subject line with a period > Trailing punctuation is unnecessary in subject lines. Besides, space is precious when you’re trying to keep them to 50 chars or less.
boogies 6y ago
Tiny tip: the 's' in 'changes' is the fiftieth character in the top commented out instruction line git puts immediately below your commit message.
noahdesu 6y ago
I'll take this further: I think that bad commit messages breed resentment. It's highly context dependent, but needing to understand some code and its historical context is already a big challenge. git-blaming your way back through time only to encounter brain dump commit messages full of ambiguity and non-essential information is excruciating. Writing good commit messages--like any technical writing--is more art than procedure, and it's hard to do well without feedback and revision. I believe that commit messages should be subject to the same level of review as the code they are presumably documenting.
jmilloy 6y ago
The important parts are * write a short title, starting with a verb * include additional information from most important to least important It just doesn't matter if you write "Adds" or "Add" or "Added", use capital or lower case letters, if you use full-stops, if you include tags (like BUGFIX or FEATURE) or issue numbers. Obviously, if you or your company decides to require anything specific, that's fine, but they are just details with respect to "good commit messages". And extra info is not very useful if it isn't well-organized. In particular, a narrative is not suitable for technical writing.
brlewis 6y ago
For purpose 2 of good messages, "Help in maintaining a feature log", do folks here have experience with https://www.conventionalcommits.org/en/v1.0.0/#summary https://www.conventionalcommits.org/en/v1.0.0/#summary ?
llamataboot 6y ago
With the popularity of squash and merge these days, I feel like atomic commits have gone by the wayside. Personally, though I was in the "comments are running code and should never be used" camp for a long time, these days I'm more inclined to want a concise and clear comment on a particular thorny bit of code than a commit message Tying a PR to an issue ticket where the conversations actually happened to come to consensus on how a feature would work or what tradeoffs were made is also helpful A commit message in and of itself just doesn't have the bandwidth to give much useful context, and now with all the squashes happening, hard to see what commit did what
autogenerated 6y ago
I think the Go guideline to commit messages is exceptionally good: https://golang.org/doc/contribute.html#commit_messages https://golang.org/doc/contribute.html#commit_messages. Also: Rob Pike's Google internal rant on the very same topic https://groups.google.com/forum/#!topic/golang-dev/6M4dmZWpFaI https://groups.google.com/forum/#!topic/golang-dev/6M4dmZWpF...

47 points by ashitlerferad 6y ago

I approve this message

My recent preferred workflow is to automate commits for docs + commits inside feature branches with a tool I wrote (https://github.com/nikitavoloboev/gitupdate https://github.com/nikitavoloboev/gitupdate). It creates commits with the files changed as commit messages. The branches ideally gets squashed with proper commit message when merging so git history is clean. And no time is wasted writing commit messages that often say whatever the code should already say.

explodingcamera 6y ago
This seems like a really bad idea. Even a 2 word commit message would be better for someone who is trying to review your code, all git hosting websites include files changed anyways and it's trival to use the cli to check for that.
naavis 6y ago
In my experience commit messages shouldn't describe what was changed, they should describe why the change was made.
- nikivi 6y ago
  that is why you shouldn't waste time writing commit messages for where this not much to `why` something has changed. (i.e. docs, refactors..)
  - bithaze 6y ago
    It's really not that much time though. "templates" and ".github" are examples of such vague commit messages that they _require_ looking at the commit to understand what changed. With a short, descriptive commit message, you can just glance through the commit log.

glxxyz 6y ago

I provided extended support on a custom system for about a year at a former employer, where the whole dev team had left before I started. I once tracked a bug down to a confusing line of code that looked like it shouldn't be there. Removing this line fixed the bug. When I looked in the commit history, that line was added as the only change in a commit that had no comment. I never worked out what they intended, e.g. whether it was a fix for something else I hadn't considered. In fact, and this is probably hard to believe, I don't think there were any comments anywhere in the commit history. Fun times.

lukevp 6y ago

I prefer commit messages to be of the form #issueid - summary of issue - additional details - more details Without a blank line anywhere. This makes it really easy to review in graphical git clients because the hyphens collapse into a single line like this: #issueid - summary of issue - additional details - more details Putting a blank line makes this rollup not happen.

IE6 6y ago

Another good resource I always point my developers to: https://chris.beams.io/posts/git-commit/ https://chris.beams.io/posts/git-commit/ As someone who manages many codebases this combined with thoughtful squashed commits allows me to (1) understand at a high level what each commit does, (2) drill into each commit should I choose to in order to review what was done in more detail, and (3) review a JIRA ticket relevant to the change (which often times is more valuable than 1 and 2).

dchess 6y ago
I was reminded of this resource as well since it is likewise what I use in training folks to use git. This OPs post seems to be a condensed version of Chris's advice.

kentosi 6y ago

For anyone questioning the imperative mood ("Add module x" as opposed to "Added module x"), what helps me it to think of each commit as a patch being applied. When I think of a patch it's almost always a patch that will "do the thing" rather than "did the thing".

bredren 6y ago

I’m nearing completion of a three month solo project where I used this style of commits, using it as an opportunity to practice doing this right. Along the way I looked at some plugins for Pycharm and came across this commit templating plugin that adds easy workflow for adding scope and commit type. https://plugins.jetbrains.com/plugin/9861-git-commit-template https://plugins.jetbrains.com/plugin/9861-git-commit-templat... Does anyone use commit message templating or style like this?

ravedave5 6y ago

Adding "why" to the message isn't even mentioned. Which is better: Updating the foobar threshold Updating the foobar threshold to improve performance.

williamdclt 6y ago
The why traditionally goes into the body of the commit message

Vinnl 6y ago

Maybe just as important: make sure the changes in a commit are related. `git blame` is a criminally underused feature, possibly because the benefits only become clear after you've had the discipline of paying attention to what goes in a commit. However, being able to pull up the context of related code right from the context of the line you're looking at [1] (from my post at [2]) can be very valuable. [1] https://vincenttunru.com/img/Commits-are-documentation/annotations.png https://vincenttunru.com/img/Commits-are-documentation/annot... [2] https://vincenttunru.com/Spend-effort-on-your-Git-commits/ https://vincenttunru.com/Spend-effort-on-your-Git-commits/

ericol 6y ago
I'm totally, utterly in love with Github's "Show blame previous to this commit" feature.
graton 6y ago
Many text editors now have this feature built in. Myself I use vim and the vim-fugitive plugin. Being able to do ":Gblame" is amazing. And then being able to step back in time to see what the code looked like before this commit is great too.

swanson 6y ago

I've worked for 10 years across 20 different commercial codebases. None of this stuff about writing good commit messages really matters. No one reads old commits. The "truth" is what the current code is doing and it doesn't really matter how it got there. I'm sure someone will say "but I use the history ALL THE TIME to source dive and paragraphs of context are super helpful". This is not the case for 95% of developers or projects so I can't really endorse spending time learning this "best practice". It's fine to be aspirational, but it's such a shame if people see posts like this and think they are failures or "bad" developers or that this is a widespread practice. If it helps you personally or you have an open source project and you want to help with a changelog, knock yourself out. But there are so many more impactful skills to be learning or spending your time on if you're a working developer in a typical environment.

knappe 6y ago
I can't disagree with this more. Good commit messages are just so, so, so important. Especially when I'm triaging an issue and have no other context than the code itself. I want to know not the _what_ which the code gives me, but also the _why_ which is what the commit message provides.
- phailhaus 6y ago
  The why should not be in your source control, the why should be in comments in the code itself. There are many reasons why a line of code may have changed, and it's unreasonable to hide important contextual information in a commit and ask engineers to waste time digging through the commit history to find the initial change (which may have been in another file!).
  - deleted 6y ago
    [deleted]
  - wcarss 6y ago
    Comments almost always become lies with time, because code changes and nothing enforces that they are correct. Having commentary built into the artifact that introduced the change ensures your commentary applies to the specific change introduced. It's then possible to tell why someone did a specific thing, and also to tell how things are today, and to decide if that justification still applies, or if things no longer match the description. If you dig around a little bit, using e.g. the git pickaxe (-S), or github's excellent blame browsing tools, it's not that time consuming and you might find out some pretty surprising things.

ed25519FUUU 6y ago

I think there's a serious problem with people bikeshedding git. To squash or not squash, the types of commits, the messages in them, etc, etc ad nuasuem. I just want to easily be able to roll your changes back if there's a problem. That's all. With good tests, git bisect will find the issue regardless of how fancy and well written your commit messages are, or how squashed or un-squashed your commits are.

joshmarlow 6y ago
I see where you're coming from, but I would disagree on one thing - I always thought squashing wasn't that important until I tried to use `git bisect` in a project and found that a sizeable number of WIP commits didn't build (basically had to abandon using bisect). So I think there's a tooling reason for squashing - more effective use of `git bisect`.

nogabebop23 6y ago

I promoted something similar to all teams at my company (I'm a manager of one) and something that I thought was a no-brainer, common sense, easy win was met with very strong resistance - and mine was even more basic than these recommendations! It's great to recommend and we should keep coaching and mentoring but ultimately this is an area where I think you'd be better to go up the chain of command until you reach a benevolent dictator who can mandate criteria. I'd love to convince people based on the merits alone, but to paraphrase a common observation in academia "the resistance is high because the stakes are so low".

ericol 6y ago

I'm the half part of a 2 dev team. Last year it took me around 3 months of internal discussions between us devs and the project manager to get us to use a PR template in Github (The PM was more or less sold on the idea). Commit messages (Not mine, obviously) rarely amount to more than "Fixed <this>". And don't get me started on code comments (Non-existent, obviously). The other coder is responsible for around 90% of the new code we ship these days (The product is "frozen" because there is a better product developed by a different and larger team, but we still have clients on this one) and I also had to strong arm him into adding type hints for vars and functions (In PHP) because he is very fond of patterns (Think, SomeObjectFactoryFactoryFactory) so it would make development with PhpStorm easier. So now the code is polluted with /** * var $sometint integer */ that explain absolutely nothing.

ashton314 6y ago

When writing the subject line for a commit, I like to imagine myself explaining what I'm doing to a coworker, and I start off by saying, "applying this commit will…" and then type whatever comes after that. This explains the imperative tense. (Wait… is imperative a mood or a tense?)

graton 6y ago

An important thing for me in a commit message is the "why" of the commit. Sure it can state "changed foo to use blah". But why did they do that is often very important information. Sometimes it is very obvious from the what, but oftentimes it is not. The article didn't seem to mention this, or if it did I didn't notice it. I usually think a commit message should have a "what" changed and a "why" it changed portion. Of course putting this information in code comments may also be a wise thing to do.

mrspeaker 6y ago

How is "Do not end subject with a full stop" self-explanatory, but "Begin subject with a capital letter" not self-explanatory? Makes me suspect the author doesn't really know why they don't put a full stop ;) Now I don't know why don't you put one! I vaguely to remember reading this on the last "how to write good commit messages" blog and thinking it seemed fair, but now I can't think of a reason. Why follow grammar rules for the start of a sentence, but not the end?

rement 6y ago
Would you add a full stop in an email subject? I think of commit messages like an email. The first line is just the subject and sometimes that is all you need. The body of the commit message is for describing other details. edit: Another blog has a simple reason https://chris.beams.io/posts/git-commit/ https://chris.beams.io/posts/git-commit/ > 4. Do not end the subject line with a period > Trailing punctuation is unnecessary in subject lines. Besides, space is precious when you’re trying to keep them to 50 chars or less.

boogies 6y ago

Tiny tip: the 's' in 'changes' is the fiftieth character in the top commented out instruction line git puts immediately below your commit message.

noahdesu 6y ago

I'll take this further: I think that bad commit messages breed resentment. It's highly context dependent, but needing to understand some code and its historical context is already a big challenge. git-blaming your way back through time only to encounter brain dump commit messages full of ambiguity and non-essential information is excruciating. Writing good commit messages--like any technical writing--is more art than procedure, and it's hard to do well without feedback and revision. I believe that commit messages should be subject to the same level of review as the code they are presumably documenting.

jmilloy 6y ago

The important parts are * write a short title, starting with a verb * include additional information from most important to least important It just doesn't matter if you write "Adds" or "Add" or "Added", use capital or lower case letters, if you use full-stops, if you include tags (like BUGFIX or FEATURE) or issue numbers. Obviously, if you or your company decides to require anything specific, that's fine, but they are just details with respect to "good commit messages". And extra info is not very useful if it isn't well-organized. In particular, a narrative is not suitable for technical writing.

brlewis 6y ago

For purpose 2 of good messages, "Help in maintaining a feature log", do folks here have experience with https://www.conventionalcommits.org/en/v1.0.0/#summary https://www.conventionalcommits.org/en/v1.0.0/#summary ?

llamataboot 6y ago

With the popularity of squash and merge these days, I feel like atomic commits have gone by the wayside. Personally, though I was in the "comments are running code and should never be used" camp for a long time, these days I'm more inclined to want a concise and clear comment on a particular thorny bit of code than a commit message Tying a PR to an issue ticket where the conversations actually happened to come to consensus on how a feature would work or what tradeoffs were made is also helpful A commit message in and of itself just doesn't have the bandwidth to give much useful context, and now with all the squashes happening, hard to see what commit did what

autogenerated 6y ago

I think the Go guideline to commit messages is exceptionally good: https://golang.org/doc/contribute.html#commit_messages https://golang.org/doc/contribute.html#commit_messages. Also: Rob Pike's Google internal rant on the very same topic https://groups.google.com/forum/#!topic/golang-dev/6M4dmZWpFaI https://groups.google.com/forum/#!topic/golang-dev/6M4dmZWpF...