8 ms·

Writing good commit messages is one of those things that IMO make the difference between a dev who produces good code, and a dev who produces high quality work

Writing good commit messages is one of those things that IMO make the difference between a dev who produces good code, and a dev who produces high quality work in general. The git log is one of the main entry points to an open source (or closed source, in fact) project. Following them tells a story, and can help you understand decisions made. Imagine you have two projects to bisect. One of them has clean, atomic and descriptive commits. The other has a git log that looks like this: https://github.com/pypa/pipenv/commits/master?after=d4d54eeb39ef45a9b68c78b8fc8f66c3f5396691+1154 https://github.com/pypa/pipenv/commits/master?after=d4d54eeb... I know which one I'd want to debug. This is also the primary reason why I highly dislike merge commits: They make git logs extremely unreadable. The thing is that writing clean commits is something that is extremely easy to do. Unlike docs and tests, it's not more work (it's less, in fact) and it's not something to continuously maintain as the code changes. It's an immediate improvement you can make to your development habits that will have a consequential improvement to your QOL. You will catch bugs doing this! (Tip when writing atomic commits: Use `git add -p`. That lets you stage patch hunks.)

rocqua 8y ago
I've had something like `git add -p` in my mind for a while now, thanks for pointing me in the right direction! It was one of the few things left in git where I prefered IDE's over the plain command line.
abhishekjha 8y ago
>This is also the primary reason why I highly dislike merge commits: They make git logs extremely unreadable. I am new to git. You will have to merge eventually with somebody when you are collaborating. Can you really avoid merge commits? I don't like how `git reflog` keeps track of which hash did I switch to. I only jump to hashes for a quick run. I don't want it actually tracking that in the log. Does anybody know how to avoid that as well?
- aviraldg 8y ago
  Yes, you can rebase: https://www.atlassian.com/git/tutorials/merging-vs-rebasing https://www.atlassian.com/git/tutorials/merging-vs-rebasing (best used with --ff-only in your config to avoid unnecessary/unintentional merge commits)
- nordsieck 8y ago
  >> This is also the primary reason why I highly dislike merge commits: They make git logs extremely unreadable. > I am new to git. You will have to merge eventually with somebody when you are collaborating. Can you really avoid merge commits? Many developers prefer to only rebase, such that master looks like a single chain of commits without any branching or other administrative structure.
- drums8787 8y ago
  Agree, learn to rebase well. Having a chain of atomic, well commented commits is bliss.
gdfasfklshg4 8y ago
> This is also the primary reason why I highly dislike merge commits: They make git logs extremely unreadable. I really really disagree. If the branch has one logical commit then no merge commit is needed. Otherwise the merge commit shows what happened and more importantly that these N commits came into the mainline as a single change.
- adtac 8y ago
  I fail to see how that would be useful. Commits are supposed to be atomic, self-contained changes by themselves. More often than not, I see merge commits only when people abuse commits for temporary state of work (with useless commit messages like "fix" and "temp"). Instead, if each commit did one thing and one thing only, why would you need a visual indicator that these set of commits came from a particular branch?
  - jonahx 8y ago
    Because they are logically grouped and that grouping is often more important than the commits themselves -- together, they accomplish a higher-level goal. You want both that goal and the individual tasks which achieved it to be visible.
    - adtac 8y ago
      That information can and should be a part of the commit body. An extra commit just for that information is, in my opinion, a hack and a workaround. I guess we have fundamental differences on how a tree should be structured. It's more of a DAG in your case, but I prefer to keep a tree a tree.
      - jonahx 8y ago
        Not sure I follow your argument. How would you put information about the semantic meaning of a series of commits into "the commit body"? The only point I'm making essentially is that "the commit" is too granular to capture all the information you need about your work and its history. You need some kind of grouping mechanism as well. It doesn't have to be merge commits, necessarily. But as I understood it, your original argument was that "there is no need for anything higher level than a commit." But there clearly is imo.
duxup 8y ago
Before I recently started coding I used to be a network engineer. I worked with a LARGE team at my previous job so documentation was CRITICAL for working difficult technical issues / documenting troubleshooting / changes / etc. If you don't document what you did, what it does, and why, everything goes to hell fast (sadly some places operate like that). So for me it came naturally that you're responsible for documenting what you do as much as what you do. Working my current coding job I'm by no means the fastest coder, or the best, but man I get praise for documentation, comments, commit details. It kinda amazes me how many skills that are just straight required in one field, earn heaps of praise in others.
- jrm2k6 8y ago
  Being thorough and highly detailed is definitely something that I praise with the colleagues I have doing it well. Someone taking time to write good PRs and maintaining documentation is definitely more useful in my book that a fast coder. Good documentation reduces the bus factor by a lot, and make someone a team player in my opinion.
jgtrosh 8y ago
> (Tip when writing atomic commits: Use `git add -p`. That lets you stage patch hunks.) Tip when using patch modes: spend time learning edit mode, and IMO avoid edit mode for checkout or reset patch modes.
sly010 8y ago
Writing the good quality commit message is not that hard and is sometimes actually enjoyable (after all i get to brag about this feature / bugfix / solution). What does cause a lot of mental overhead (and consider myself a decent engineer) is creating commits that have a single purpose in the first place. Working on a new feature I often have to refactor something, and while I am at it, I clean up some related parts. That is at the minimum 3 commits applied in the correct order, sometimes over different branches. At that point there is a lot of `git add -p` and `git stash apply` going on, which takes considerably more mental energy while you see some colleagues getting away with `git commit -a`. Writing good commit messages itself is the reward for creating good commits.
- invalidOrTaken 8y ago
  YES. It's very easy to write good commit messages; what's much harder is making "good" (as in: atomic, understandable) commits. I know I'm just restating what you said, but...I just agree very strongly.
  - gregmac 8y ago
    Part of the problem is it's not obvious why you need to do this until you need it, at which point it's too late. Reasons include: understanding how a change works (all related code in one place without extra distraction), easy to revert, easy to figure out why that code is there during a blame.
- notyourwork 8y ago
  > What does cause a lot of mental overhead (and consider myself a decent engineer) is creating commits that have a single purpose in the first place. I agree, this is what demonstrates maturity in an engineer. Perhaps we need to focus on commit driven development. I personally do not allow teammates to ship macro commits covering multiple features. I call this out in code review process.
- awolf 8y ago
  Rather than `git add -p`, I suggest creating a second clone of your repo, staging your foundational refactor changes in the second repo, creating and merging your commits there, and then rebasing your working branch. This makes sure you can fully test your refractors and that their change sets stand alone.
wpietri 8y ago
When I clicked on that link, I was totally prepared to say, "Well that's not that bad." But wow, that's bad. If I were looking at getting involved, that could be enough to stop me. And all those broken builds might be enough to keep me from using the project at all.
- scrollaway 8y ago
  Yeah the awful git log is one of the things that turned me off contributing to pipenv. They got better at it, FWIW.
BerislavLopac 8y ago
The trick I've developed to improve my commit messages is to ask my self how would I explain something to do what the commit does, in a widest sense. Before that my messages either amounted to "HAAAAANDS" (https://xkcd.com/1296/ https://xkcd.com/1296/ -- there is always an appropriate XKCD), or tended to go into minutiae of implementation ("added a boolean attribute 'foo' and changed method 'bar' to raise FooBarBazException when the calculated value is 42"). The "instructions" approach helps me focus on why something was done ("implement verification of the IMO field") than how (which should generally be obvious from the code itself).
- krispbyte 8y ago
  My commits are the exact opposite of that comic. My initial commits are unfocused since it's the start of the project and there's a lot going on. As the project stabilizes and changes are smaller and on point, the commit messages become more focused as well.
  - BerislavLopac 8y ago
    I prefer to avoid "intermediary" WIP commits at all. Of course, I still make such commits to avoid losing my work, but I continuously amend the first commit rather then creating new ones (unless I'm experimenting, which goes to a separate branch anyway). Multiple commits usually lead to a rebase before merging, which tends to be more difficult than amending.
atq2119 8y ago
> (Tip when writing atomic commits: Use `git add -p`. That lets you stage patch hunks.) Also take a look at `git gui`, which is part of Git core.
tome 8y ago
> (Tip when writing atomic commits: Use `git add -p`. That lets you stage patch hunks.) Even better, use `git commit -p` and skip the staging area entirely.
- u801e 8y ago
  > Even better, use `git commit -p` and skip the staging area entirely. If you end up staging the wrong hunk, then you will have to reset and recommit. With git add -p, you would only need to reset the hunk.
  - tome 8y ago
    You indeed have to recommit everything (which I prefer) but you don't have to reset anything (since nothing is in the staging area).
    - u801e 8y ago
      >> If you end up staging the wrong hunk, then you will have to reset and recommit > you don't have to reset anything You have to reset the branch pointer to the previous commit, but I think using the --amend switch may do that for you.
      - tome 8y ago
        If you exit the commit message editor so that it retuns a non-zero exit code to git then nothing is committed and nothing is staged.
        dllthomas 8y ago
        With git, usually (maybe always?) exiting having saved an empty buffer is equivalent.
rakoo 8y ago
> The other has a git log that looks like this That's because, like GitHub itself, the documentation for them is not in the commit messages but in the pull-requests. Look at their PR page (https://github.com/pypa/pipenv/pulls https://github.com/pypa/pipenv/pulls) and individual PRs, you'll see that it's much better organized. The difference is that now the source of truth is not git itself, but wherever the pull-requests are.
- ajmurmann 8y ago
  That really ruins a lot of tooling. Going back through history to see when a bug might have been introduced; doing git blame to find out why a line of code is like it is... If you write his commit messages, you also get good PR messages for free.
- ajross 8y ago
  > the source of truth is not git itself, but wherever the pull-requests are. And you think storing that source of truth separately from the code is... a good thing?
  - rakoo 8y ago
    I personally don't, that was just a way to explain the whys. But this whole thing is probably a good reason to ask whether staying in git, the completely decentralized VCS, to work in a centralized manner, is the best way to go. As the sibling comment evocated, our traditional tooling is limited in that way of working but that doesn't mean it's inherently bad; maybe we need new tools?

rocqua 8y ago

I've had something like `git add -p` in my mind for a while now, thanks for pointing me in the right direction! It was one of the few things left in git where I prefered IDE's over the plain command line.

abhishekjha 8y ago

>This is also the primary reason why I highly dislike merge commits: They make git logs extremely unreadable. I am new to git. You will have to merge eventually with somebody when you are collaborating. Can you really avoid merge commits? I don't like how `git reflog` keeps track of which hash did I switch to. I only jump to hashes for a quick run. I don't want it actually tracking that in the log. Does anybody know how to avoid that as well?

aviraldg 8y ago
Yes, you can rebase: https://www.atlassian.com/git/tutorials/merging-vs-rebasing https://www.atlassian.com/git/tutorials/merging-vs-rebasing (best used with --ff-only in your config to avoid unnecessary/unintentional merge commits)
nordsieck 8y ago
>> This is also the primary reason why I highly dislike merge commits: They make git logs extremely unreadable. > I am new to git. You will have to merge eventually with somebody when you are collaborating. Can you really avoid merge commits? Many developers prefer to only rebase, such that master looks like a single chain of commits without any branching or other administrative structure.
drums8787 8y ago
Agree, learn to rebase well. Having a chain of atomic, well commented commits is bliss.

gdfasfklshg4 8y ago

> This is also the primary reason why I highly dislike merge commits: They make git logs extremely unreadable. I really really disagree. If the branch has one logical commit then no merge commit is needed. Otherwise the merge commit shows what happened and more importantly that these N commits came into the mainline as a single change.

adtac 8y ago
I fail to see how that would be useful. Commits are supposed to be atomic, self-contained changes by themselves. More often than not, I see merge commits only when people abuse commits for temporary state of work (with useless commit messages like "fix" and "temp"). Instead, if each commit did one thing and one thing only, why would you need a visual indicator that these set of commits came from a particular branch?
- jonahx 8y ago
  Because they are logically grouped and that grouping is often more important than the commits themselves -- together, they accomplish a higher-level goal. You want both that goal and the individual tasks which achieved it to be visible.
  - adtac 8y ago
    That information can and should be a part of the commit body. An extra commit just for that information is, in my opinion, a hack and a workaround. I guess we have fundamental differences on how a tree should be structured. It's more of a DAG in your case, but I prefer to keep a tree a tree.
    - jonahx 8y ago
      Not sure I follow your argument. How would you put information about the semantic meaning of a series of commits into "the commit body"? The only point I'm making essentially is that "the commit" is too granular to capture all the information you need about your work and its history. You need some kind of grouping mechanism as well. It doesn't have to be merge commits, necessarily. But as I understood it, your original argument was that "there is no need for anything higher level than a commit." But there clearly is imo.

duxup 8y ago

Before I recently started coding I used to be a network engineer. I worked with a LARGE team at my previous job so documentation was CRITICAL for working difficult technical issues / documenting troubleshooting / changes / etc. If you don't document what you did, what it does, and why, everything goes to hell fast (sadly some places operate like that). So for me it came naturally that you're responsible for documenting what you do as much as what you do. Working my current coding job I'm by no means the fastest coder, or the best, but man I get praise for documentation, comments, commit details. It kinda amazes me how many skills that are just straight required in one field, earn heaps of praise in others.

jrm2k6 8y ago
Being thorough and highly detailed is definitely something that I praise with the colleagues I have doing it well. Someone taking time to write good PRs and maintaining documentation is definitely more useful in my book that a fast coder. Good documentation reduces the bus factor by a lot, and make someone a team player in my opinion.

jgtrosh 8y ago

> (Tip when writing atomic commits: Use `git add -p`. That lets you stage patch hunks.) Tip when using patch modes: spend time learning edit mode, and IMO avoid edit mode for checkout or reset patch modes.

sly010 8y ago

Writing the good quality commit message is not that hard and is sometimes actually enjoyable (after all i get to brag about this feature / bugfix / solution). What does cause a lot of mental overhead (and consider myself a decent engineer) is creating commits that have a single purpose in the first place. Working on a new feature I often have to refactor something, and while I am at it, I clean up some related parts. That is at the minimum 3 commits applied in the correct order, sometimes over different branches. At that point there is a lot of `git add -p` and `git stash apply` going on, which takes considerably more mental energy while you see some colleagues getting away with `git commit -a`. Writing good commit messages itself is the reward for creating good commits.

invalidOrTaken 8y ago
YES. It's very easy to write good commit messages; what's much harder is making "good" (as in: atomic, understandable) commits. I know I'm just restating what you said, but...I just agree very strongly.
- gregmac 8y ago
  Part of the problem is it's not obvious why you need to do this until you need it, at which point it's too late. Reasons include: understanding how a change works (all related code in one place without extra distraction), easy to revert, easy to figure out why that code is there during a blame.
notyourwork 8y ago
> What does cause a lot of mental overhead (and consider myself a decent engineer) is creating commits that have a single purpose in the first place. I agree, this is what demonstrates maturity in an engineer. Perhaps we need to focus on commit driven development. I personally do not allow teammates to ship macro commits covering multiple features. I call this out in code review process.
awolf 8y ago
Rather than `git add -p`, I suggest creating a second clone of your repo, staging your foundational refactor changes in the second repo, creating and merging your commits there, and then rebasing your working branch. This makes sure you can fully test your refractors and that their change sets stand alone.

wpietri 8y ago

When I clicked on that link, I was totally prepared to say, "Well that's not that bad." But wow, that's bad. If I were looking at getting involved, that could be enough to stop me. And all those broken builds might be enough to keep me from using the project at all.

scrollaway 8y ago
Yeah the awful git log is one of the things that turned me off contributing to pipenv. They got better at it, FWIW.

BerislavLopac 8y ago

The trick I've developed to improve my commit messages is to ask my self how would I explain something to do what the commit does, in a widest sense. Before that my messages either amounted to "HAAAAANDS" (https://xkcd.com/1296/ https://xkcd.com/1296/ -- there is always an appropriate XKCD), or tended to go into minutiae of implementation ("added a boolean attribute 'foo' and changed method 'bar' to raise FooBarBazException when the calculated value is 42"). The "instructions" approach helps me focus on why something was done ("implement verification of the IMO field") than how (which should generally be obvious from the code itself).

krispbyte 8y ago
My commits are the exact opposite of that comic. My initial commits are unfocused since it's the start of the project and there's a lot going on. As the project stabilizes and changes are smaller and on point, the commit messages become more focused as well.
- BerislavLopac 8y ago
  I prefer to avoid "intermediary" WIP commits at all. Of course, I still make such commits to avoid losing my work, but I continuously amend the first commit rather then creating new ones (unless I'm experimenting, which goes to a separate branch anyway). Multiple commits usually lead to a rebase before merging, which tends to be more difficult than amending.

atq2119 8y ago

> (Tip when writing atomic commits: Use `git add -p`. That lets you stage patch hunks.) Also take a look at `git gui`, which is part of Git core.

tome 8y ago

> (Tip when writing atomic commits: Use `git add -p`. That lets you stage patch hunks.) Even better, use `git commit -p` and skip the staging area entirely.

u801e 8y ago
> Even better, use `git commit -p` and skip the staging area entirely. If you end up staging the wrong hunk, then you will have to reset and recommit. With git add -p, you would only need to reset the hunk.
- tome 8y ago
  You indeed have to recommit everything (which I prefer) but you don't have to reset anything (since nothing is in the staging area).
  - u801e 8y ago
    >> If you end up staging the wrong hunk, then you will have to reset and recommit > you don't have to reset anything You have to reset the branch pointer to the previous commit, but I think using the --amend switch may do that for you.
    - tome 8y ago
      If you exit the commit message editor so that it retuns a non-zero exit code to git then nothing is committed and nothing is staged.
      - dllthomas 8y ago
        With git, usually (maybe always?) exiting having saved an empty buffer is equivalent.

rakoo 8y ago

> The other has a git log that looks like this That's because, like GitHub itself, the documentation for them is not in the commit messages but in the pull-requests. Look at their PR page (https://github.com/pypa/pipenv/pulls https://github.com/pypa/pipenv/pulls) and individual PRs, you'll see that it's much better organized. The difference is that now the source of truth is not git itself, but wherever the pull-requests are.

ajmurmann 8y ago
That really ruins a lot of tooling. Going back through history to see when a bug might have been introduced; doing git blame to find out why a line of code is like it is... If you write his commit messages, you also get good PR messages for free.
ajross 8y ago
> the source of truth is not git itself, but wherever the pull-requests are. And you think storing that source of truth separately from the code is... a good thing?
- rakoo 8y ago
  I personally don't, that was just a way to explain the whys. But this whole thing is probably a good reason to ask whether staying in git, the completely decentralized VCS, to work in a centralized manner, is the best way to go. As the sibling comment evocated, our traditional tooling is limited in that way of working but that doesn't mean it's inherently bad; maybe we need new tools?