Git commit messages are useless
trunk.io
trunk.io
It seems like the workflow where you get 20 "stuff" commits in a PR is to: git commit -am "stuff", test it, see that it doesn't work, make another change, hit up then enter on the shell window, test it, and so on.
If this is how you prefer to develop then I think testing first and squashing along the way might be better:
- initial change, test, worked? git add <files>, git commit -m "meaningful summary\n\n- meaningful note"
- small change: test, didn't work, git reset --hard
- another attempt: test, worked, git add, git add <files>, git commit --amend (new meaningful note)
If the steps you're taking to get to the end are meaningful or significant (maybe for a bisect in the future) then just commit with a meaningful message along the way.
More generally, I think it's more common create commit messages for "me", the writer, and not for the reader. Try instead writing commit messages (comments, documentation..) for an audience who doesn't have the context you have. For example: Nathan in 7 (or 2) years time who is tracking down the reason for a change you made which he suspects is the cause of a bug he's trying to fix.
It turns out that a coworker had discovered the --amend flag, but spelled it as -amend, and so it was interpreted as -a -m "end"
That's a good example why simple is good. Less surface for mistakes to happen.
If you did one "thing" on a PR branch, and it took you 10 commits to do it, those 10 should be squashed to one, and the commit message should be "Added thing."
If you did 3 "things" on a PR branch, and it took you 10 commits, you should squash those 10 into 3 semantically meaningful commits: "Added Thing#1" "Added Thing#2" "Added Thing#3" This is doubly true if you ran into some complexity during the implementation that caused you to have to do the extra stuff -- that's exactly the type of detail someone looking back on commits needs to understand the development history.
This is something that you are not allowed to do under most squash-merge policies, because "1 PR == 1 commit" for maximum legibility.
Of course, nobody ever takes the time to do any of this which is how we ended up with such policies in the first place.
> With modern trunk-based engineering, pull request branches are squash-merged onto main
Commit messages are useless because of squash-merges, yes. However, my opinion is that it's the very concept of squash-merges that is the problem, not commit messages. Squashing eliminates all sorts of valuable information, and I think it's harmful.
"oh. i should fix this, but it doesn't have anything to do with what i'm currently solving." cd ../worktree-checkout, make a branch, do the fix, push, open a pr. then cd ../original-checkout and continue on. rebasing the fix into my wip when the PR is merged (or cherry-pick if you're confident) as needed.
In my opinion, a VCS should maintain a history of all commits, because it's impossible to know which commits will be the key to solving a problem in the future. Even commits that are later reversed can occasionally be of tremendous value.
A truly great VCS would allow you to do a "visual squash", hiding the intermediate commits unless you need to see them.
If Github's UI showed branches diverging, commits being made to that branch, then the merge back to trunk like gitk does then devs could visually see why it's valuable.
Works best if your merge commits have useful messages.
I think you need to recognize that you have some implicit assumptions about what a commit even is, when you make such statements as “all commits [should be preserved]”.
In that frankly ridiculous example, nothing has actually changed but the location and the label for where the meaningful thing happens.
In your example, since you've artificially injected automation to snapshot every 11th keystroke, those keystrokes and those commits are indeed not meaningful. (I would argue that they're not useful either but I allow it's possible to argue they're useful)
But there is still some point where you do decide "here there is a meaningful milestone" and you mark that spot.
Other people do exactly that same thing with commit.
You've just artificially gone out of your way to make your own commits useless for that.
Why? It’s super helpful for me. It makes me a better engineer, and nobody I work with has to care that this is happening, because it’s all gone by the time I make a PR. Why is it “wrong?” Because you have a certain definition in your head about what a commit “is”, and are making a bunch of blanket statement based on this assumption, and everyone who has different assumptions is therefore wrong?
To be fair, I don’t run “git commit” in a loop. I do however, commit extermely early and extremely often. I commit just about every time the code compiles, whether I’m done with what I’m doing or not. Whenever I decide “hmm, approach A isn’t working great, let me try approach B”, I make a commit. If approach B doesn’t work out either, I can compare it with my commit at approach A and decide which elements I want to take from both. I can create branches to do make this easier, so that I can switch between them at will.
The point is, I make commits at what should be considered arbitrary points in time, because for me, a commit doesn’t mean “a thing I want someone to review”. A commit means “I don’t trust my editor not to crash and wipe my undo history, so I’m going to create a checkpoint right now in case of a crash or sudden power loss”. Who are you to judge me for this? Why is it wrong?
> But there is still some point where you do decide "here there is a meaningful milestone" and you mark that spot.
Right, that’s called “a pull request”. It’s the reviewable unit of my productivity. When I decide “here is a thing I believe should be merged”, I put up a PR. I don’t believe this needs to be broken further into the endless commits that it took me to arrive at this point.
> You've just artificially gone out of your way to make your own commits useless for that.
No, I’ve gone out of the way to save my work. Git commit is extremely good at this, because it lets me save my work in a way that supports branches, which my editor’s undo history does not. It lets me compare these units of saved work in a way no editor can (even for editors which support branching undo history.) But with this workflow naturally comes the conclusion that I must squash all of this into one meaningful commit (with a good commit message) once it’s ready to be reviewed. There’s no reason whatsoever that anyone should care that I typed “git commit -am wip” a bunch of times while getting to that point.
WIP commits should be rebased out before the branch is pushed
Commits which fix formatting should definitely be a separate commit so they can be added to `.git-blame-ignore-revs`. This allows anyone looking through the history of a change to see the functional fix, rather than having it mixed in with a refactor/reformat operation.
In this case, each commit should have a useful commit message, both allowing them to be searchable, and to help understanding of the change
(I agree on all points.)
Instead of finding an offending commit that has only a few lines to analyze, you only get a massive feature-landing commit that doesn't narrow it down.
Interactive rebase or amend can be used to squash "oops forgot a semicolon" junk commits.
Squash is basically a hard requirement for bisect to be useful at all. Especially for compiled languages.
Anyway, accidentally-breaking commits can be skipped, but squashed commits can't be unsquashed.
A commit that only changes formatting is a prime example of a useful secondary commit. Separating formatting changes from code changes makes it much easier to see what the actual functional changes were rather than them being hidden in a mess of non-functional changes.
Github is the problem here. And squash merge is "useful" as in when I would have squashed a commit even before merging, I don't think we should squash merge otherwise
For me commits is just backup/save.
The PR contains details.
It's a higher discipline activity but it's really worth it.
You can have a 3 person team work with such policies. But it is unworkable for a huge repo.
It's absolutely not limited to three people teams.
>Git recently added an --allow-empty-message flag, but really this is backwards. Commit messages should be empty by default. If you want to name your save points, you should have to do so explicitly. Actually, why doesn’t it just constantly autosave your work, like editing text anywhere else (Google Docs, Notion, etc.)?
If I were to clone a repo and find empty commit messages I would probably flip a table and refuse to work on it. This is a terrible idea. How would you use git bisect without commit messages?
The tool should not allow people to do things just because it feels easier.
>We all write them, and they cost the collective engineers of the world countless hours writing ridiculous messages like, “changed something”, “did work”, or the super descriptive, “stuff”.
These kinds of commit messages are typically an indicator of a broken process where somebody needs to commit to see something happen, like a deployment or build process, and aren't able to assert that stuff works locally.
I think the problem comes down to many people just using git as a glorified storage drive for code and not really understanding how to get the most out of the tool.
This is one of my biggest pet peeves with services like github actions. Something running locally like "act" [1] isn't sufficient because it doesn't have everything github has and is extra friction anyway to get everyone to use it for testing.
The trouble is that Git is trying to do two things at once. It's trying to do remote synchronization as well as change tracking all at once.
An alternative is just to do "git commit --amend" every time you want to fix some small bug, but that has downsides in preventing reviewers from seeing what has changed between PR iterations as well as preventing you from going back to an earlier point in time for some branch. When you have less than a dozen commits, it is completely reasonable to just look at diffs and timestamps to determine which commit you want to go back to.
There are very good reasons not to enable squash merges. For example, code formatting changes should almost always be in a commit of their own and not squashed together with a refactor or new feature. If you bundle these changes together, git blame output becomes a mess and it's more difficult to distil what the actual changes were in a commit.
Crafting intelligent commits is a skill in itself that more engineers need to learn.
It can also get confusing as a reviewer if people do any rebasing after submitting the PR.
Combine the flexibility of the shell and git aliasing, and I just don't understand how they could possibly be complaining about this.
I am making a VCS that works exactly like this!
* Commits on personal branches are called "saves," and they are meant to be an undo/redo history that can be discarded.
* Saves don't need commit messages.
* Saves can only be merged into designated branches, and those merge commits need real commit messages.
* Saves can be rebased as much as possible.
* Commits on master/main cannot be rebased. (There will be a nuclear option for things that should have been secret.)
There are other things, but that is the gist.
I am not just developing the VCS for those features. It's also to solve the large file problem, the binary file problem, and the centralization problem.
git config --global alias.wip '!git add . && git commit -m "WIP"'
For a recent project, I didn't push to GitHub for about 8 weeks. No point. Just one extra step. Only benefit is if I lose my laptop I've got a backup. But there's a backup on heroku. So the only time I'd need the GitHub version is if both my laptop went missing (hasn't ever happened, but I cede it could happen), and heroku somehow loses it (again, has never happened, but I guess it could).
I try to write one line commit messages, mostly for posterity. Ive had some nice moments looking back on the "OMG it works" projects
Instead , people should write WHY are those changes being made. That's info that cannot be generated automatically, they surely have at the moment in time they are making the change and most importantly, that's the question that another dev will be asking himself 5 years later when reviewing the commit in the middle of a code archeology session: "why the heck did they do that??,"
I think this is the consequence of git's model - there is continuous interaction happening locally.
It is important to save your work. I've even wondered if there should be "autosaves" just like in video games.
In other (centralized/shared) version control systems, the commit messages are important and well thought out, because a commit is when you merge your work with other people's work.
I think that point is when you should be prompted to enter a comment - it might even be required.
somewhat related, I also hate that when looking at files in gitlab, it shows the commit message beside each file, where more intuitively it should describe the file
That being said, this is the only reason I think of for writing a commit message. After adding the commits into master (via rebase preferably), I've rarely read a commit message.
It's just my preference. It's more important to enforce a consistent repository rule.
I would much prefer to use commit messages this way. I kind of do, but only half-way because someone else might read them and want information relevant to them, not just to me. But what I actually want is a message by me, for me, since I am far and way the most likely person to ever read it.
For the meme illiterate, please refer to the big lebowski...
NOTE: meme illiteracy is the condion of not being able to understand anything without references to a popular internet meme
> Requiring commit messages is a vestige of engineering practices from the ancient times of the mid-aughts.
I know it's been ~20 years, but hardly ancient. I suppose it's ancient to the young?
> With modern trunk-based engineering, pull request branches are squash-merged onto main — and all those silly commit messages are thrown out in the process.
I do work that way; but those commits are still preserved in git history on the branch I cut the PR from. People have gone back and read them! They've told me as much!
But also worth noting that this is a very github/gitlab-centric workflow; certainly the kernel devs don't work that way.
> You shouldn’t have to show your work like you did in school.
Commit messages aren't for showing your work, they're for explaining why you did what you did at a given point.
---
Honestly, in some ways I kinda see the point. But if you're not disciplined enough to squash your damn commits on your branch and re-write messages as-needed there, I just don't believe you're disciplined enough to write good PR messages. The author alludes to this when talking about how the real good stuff is captured in slack, google docs, etc. (all infinitely less-discoverable, especially as time marches on... but I digress). And if you aren't disciplined to write good PR messages either, then who really cares what your git history looks like at that point.
I work with and have worked with a lot of engineers with this general mindset - "the real information is in a meeting doc" or whatever - and it honestly sucks. Systems are less reliable, work is of poorer quality, lots of unnecessary work gets done, etc. It's a bad way to do engineering, and there's no other way to put it.
But they're absolutely not worth spending a lot of time on. Write something and move on. I still commit a lot less than I should, and regularly regret not having committed, because I spent 4 years working at a place that required meaningful commit messages and that trained me out of committing early and often. Don't be that guy.
But definitely don't squash on merge. You lose all the advantages of git; you can't pull from other people's branches because their commits are going away, you can't automated bisect because you'll just land on your squashes. If you're going to squash then why even bother using git?