89 things I know about Git commits (abridged version)

Jamie Tanna he/him

Chief Blogger @ https://www.jvt.me

89 things I know about Git commits

https://www.jvt.me/posts/2024/07/12/things-know-commits/

  1. Git has different uses - a collaboration tool, a backup tool, a documentation tool
  2. Git commit messages are excellent
  3. I've never met anyone who likes reading commit messages as much as me
  4. Finding out why a change was made is easier sorting through commits than it is through an issue/bug tracker
  5. It's better to have a commit that says "Various fixes. DEV-123" than it is to have "Various fixes"
  6. It's worse to have a commit that says "Various fixes. DEV-123" when the issue itself has no useful information
  7. Rebase-merging is my preference. Then squash-merge, then merge
  8. If you don't learn how to rebase, you're missing out on a good skill
  9. People who say "just delete the repo" when things go wrong really frustrate me
  10. Learn how to use git reflog, and it'll save you deleting a repo and work that was recoverable
  11. Learn how to use git reflog, and you'll be able to save yourself from mistakes that aren't that bad
  12. No amount of learning fancy tools and commands saves you from fucking up every once in a while
  13. My most recent botched rebase was last week, and I needed git reflog to help un-fuck it
  14. Learn how to undo a force push and then how to more safely force push (remember the =ref!!)
  15. Squashing is a waste of well-written atomic commits
  16. Squashing is better than 100 crap commits
  17. Squashing, and writing a good commit message at the time of merge is good
  18. Squashing, and then not re-editing the message is the worst
  19. Squashing, when you have 100 crap commits, and then not re-editing the message is a crime
  20. Squashing, and then not re-editing the message is worse than a merge commit from a branch with 100 crap commits
  21. Writing a well documented PR/MR description but not using that to inform the squash-merge message is a waste of time
  22. Writing commit messages have helped me pick up on missing test cases, missing documentation, or invalid thought processes, as it helps me rewrite why the changes are being made
  23. Using your git log as an indication for standup updates is valid
  24. I can't be bothered to sign my commits (unless I'm forced to)
  25. If I have to sign my commits, SSH key signing makes it almost not awful
  26. If you're moving files between repos, you need to keep the history intact, using git subtree
  27. Commits should be atomic - all the code and tests, and configuration changes should all be in there
  28. I spend a good chunk of time ensuring that each commit passes CI checks atomically
  29. Some people do horrific things, like split their implementation and test code from each other
  30. It's OK to put documentation in a separate commit - we don't have to have a whole end-to-end feature delivery in a single commit
  31. Repos that use squash-merges suck
  32. As a maintainer of Open Source projects, I like squash-merge, so I can rewrite contributors' commit messages
  33. Sometimes it's not worth coaching how to write a given commit message
  34. The people around you shape the way you write commits
  35. Do the work up front to make your history atomic
  36. It's much more painful to split a mega-commit into atomic commits after the fact
  37. Splitting work atomically can be good for improving your reward drive - you can get many more things done
  38. Atomic commits work really well with prefactoring
  39. Sometimes prefactor commits can go into separate PRs (especially if squash-merge is used)
  40. Writing commit messages can take longer than the implementation
  41. The commit message can be an order of magnitude larger than the number of lines changed in a commit
  42. If you end up writing a lot of "and"s or "also" in a commit message, you may be trying to do too many things
  43. Trawling through Git commit history in the past has helped unlock a number of cases where I could then understand the why without the original authors there to answer my questions
  44. Commit messages are a great point to reflect on not just what you've done, but why
  45. Why is more important than what - anyone can look at the diff and generally work out what changes were made, but the intent behind it is the special sauce
  46. If you only write what changed, you're annoying, and I dislike you
  47. A commit that explains what is better than a commit that just has "fixes"
  48. Chris Beams' article, How to Write a Git Commit Message is still an excellent post and a great place to start, just under 10 years later!
  49. Commits are a point-in-time explanation of the assumptions and the state of the world for the committer. Don't be too hard on them
  50. I don't want to read AI/LLM rewrites of your changes - either write it yourself, or call it Various fixes
  51. There needs to be a way to add an annotation (maybe using git notes) to a previous message to correct assumptions
  52. I won't write perfect commit messages up front - they'll sometimes be as much as rew! add support for SBOMs or sq, or use git commit --fixup
  53. I will, generally, break off very good atomic chunks of work into commits
  54. I will split atomic commits into multiple commits, sometimes
  55. Make sure you review your own code changes before you send it out for review to your collaborators
  56. Reviewing your commit messages should be as important as reviewing the code changes
  57. Getting all your contributors to invest the same amount of care into the commit history is a losing battle
  58. Trying to police commit history is going to be painful
  59. Trying to mandate reviews of commit messages as part of code review is going to be painful
  60. Trying to police commit history does lead to a greater level of documentation and consideration around changes int he codebase
  61. Making implicit assumptions explicit is really useful
  62. Introducing commitlint can be useful, but also frustrating
  63. It's nicer to have your collaborators want to write good commit messages than you having to force them
  64. Some people don't write, and that's alright
  65. Writing is a skill
  66. I'm not perfect at writing (commit messages)
  67. Sometimes I can't be arsed to write the perfect message
  68. Sometimes I write some really great commit messages, and impress myself
  69. Using a template for your Git commit messages is a good nudge to doing it right
  70. fixup commits and git rebase --autosquash has been one of the best Git tips I've learned
  71. I value working on a team with a diverse set of perspectives, skills and approaches to work
  72. But I also really value having a team who writes atomic commits with well-written commit messages
  73. Commit message writing is as useful as writing well-refined user stories/tickets
  74. git commit -m sq is probably my most-run command
  75. Using git add -p and git commit -p are hugely important for atomic commits
  76. Never use git add -u or git add .
  77. Learn when you can use git add -u or git add .
  78. I really need to look into tools like Graphite, git-branchless and other means to provide a stacked PR setup
  79. Using conventional commits with semantic-release or go-semantic-release can make a huge difference when wanting to release automagically and often
  80. Using conventional commits as a framework for your commits can be really useful
  81. Using conventional commits, as someone with ADHD, reduces the need for thinking at times and can allow you to focus more on what the changes are
  82. Using conventional commits helps you work out when you're trying to do too much in a commit
  83. I think through writing so commit messages help understand why I did the thing
  84. It can be better to write a good commit message than a piece of documentation, stored elsewhere
  85. It can be better to write a good commit message than a code comment
  86. Give people space to learn
  87. Give people space to fail
  88. Remember you weren't so great at one point in time
  89. Documentation is rad. Do more of it

Thanks for having me!

Git has different uses - a collaboration tool, a backup tool, a documentation tool

Git commit messages are excellent

I've never met anyone who likes reading commit messages as much as me

  • It's better to have a commit that says "Various fixes. DEV-123" than it is to have "Various fixes"
  • It's worse to have a commit that says "Various fixes. DEV-123" when the issue itself has no useful information
  • People who say "just delete the repo" when things go wrong really frustrate me
  • Learn how to use git reflog

No amount of learning fancy tools and commands saves you from horribly messing up every once in a while

Squashing is:

  • a waste of well-written atomic commits
  • better than 100 crap commits
  • Squashing, and writing a good commit message at the time of merge is good
  • Squashing, and then not re-editing the message is the worst
  • Squashing, when you have 100 crap commits, and then not re-editing the message is a crime
  • Squashing, and then not re-editing the message is worse than a merge commit from a branch with 100 crap commits

Writing commit messages have helped me pick up on missing test cases, missing documentation or invalid thought processes, as it helps me rewrite why the changes are being made

Commits should be atomic - all the code and tests, and configuration changes should all be in there

  • Repos that use squash-merges suck
  • As a maintainer of Open Source projects, I like squash-merge, so I can rewrite contributors' commit messages

Splitting work atomically can be good for improving your reward drive - you can get many more things done

Writing commit messages can take longer than the implementation

The commit message can be an order of magnitude larger than the number of lines changed in a commit

  • Why is more important than what - anyone can look at the diff and generally work out what changes were made, but the intent behind it is the special sauce
  • If you only write what changed, you're annoying, and I dislike you

Commits are a point-in-time explanation of the assumptions and the state of the world for the committer. Don't be too hard on them

I don't want to read AI/LLM rewrites of your changes - either write it yourself, or call it Various fixes

Getting all your contributors to invest the same amount of care into the commit history is a losing battle

  • Some people don't write, and that's alright
  • Writing is a skill
  • I'm not perfect at writing (commit messages)
  • Sometimes it's not worth coaching how to write a given commit message
  • Give people space to learn
  • Give people space to fail
  • Remember you weren't so great at one point in time

Do the work up front to make your history atomic

Documentation is rad. Do more of it

Thanks for having me!