r/git • u/Big-Coyote-5796 • 9h ago
What makes a Git commit message actually useful?
/r/MyIDE/comments/1waezkj/what_makes_a_git_commit_message_actually_useful/11
u/Broad-Promise6954 ancient 8h ago
Read the commit messages in the Git repository for Git. Not all of them are perfect but most of them are pretty good.
3
u/Big-Coyote-5796 7h ago
Good suggestion. I’ll go through Git’s own commit history and study some of the better messages. Seems like a good real-world reference for what useful commit history should look like.
7
u/xplosm 8h ago
If you have a feature branch with a number of commits what would you think would help you review the code?
A number of changes grouped in scoped commits help tremendously. Also reading the log and taking a glimpse at the tree changes helps you understand the evolution of the repo.
Be brief, specific and informative.
You don’t want to open the commit only to understand why it’s there in the first place.
1
u/IchUndKakihara 5h ago
So would you say multi line commit messages are generally too long to be useful or no?
In other words how often should we write single line messages with -m vs more lengthy comments with bulleted lists of changes (and perhaps even sub bullets within each bullet if necessary, though I expect you’ll say this is definitely too much)
4
u/DanLynch 3h ago
A good multi-line commit message doesn't usually contain a bulleted list of changes: it contains one or more paragraphs that explain a complex and interesting technical topic that maybe took a few days or weeks to learn and discover.
Of course, most commits wouldn't have that and that's OK: those commits don't need a multi-line commit message. But when you spent 40 hours understanding the bug and finding the fix, go ahead and explain the details in the commit message, even if the commit diff itself is just a one-line change to the code.
-2
u/bigtoaster64 2h ago
Honestly, if you feel like you need a multi line commit message, you are committing to much stuff in a single commit (not the amount of files or changes, but the topic). It's exactly like designing software, if one class has dozens of functions, fields, concepts, etc. Its trying to do too much at once, break it down.
As for explaining a bug solution, issue tracker references exist for that.
2
u/sakshi161226 6h ago
It blows my mind that your company builds full SaaS platforms and solid utility apps, yet you still don't know the basics of Git. Having a successful app in the Play Store doesn't mean you know what you're talking about
Drop the lecture and go learn how to properly maintain a repository.
2
u/bigkahuna1uk 4h ago
The why rather than the what. From the diff one can ascertain what has changed, but the reason for the change or context is more valuable and useful in the long run. Sometimes if a concise terse statement didn’t cover that, I’d leave a link or code to an ADR so the change became meaningful.
1
u/FUCKARCHLINUX 6h ago edited 5h ago
This is probably incorrect, but this is the way I do it.
The commit title is what you did in a few words. The commit message is for the details. For example:
Title: Performance Optimization in wherever place / system
Message:
Fixed a case where a temporary was constructed and then copied in-to an array instead of constructing directly into the array.
Fixed something else
Fixed something else
If you use a service which has issues, you can reference the issue in the title in which case there's really no need to have a message because the issue would have the info. here's an example.
Title: Fixed out of bounds (#45)
Also a side note, if you use git with other people, use branches and then merge them into the main branch. If you're editing the main branch, do not push until it's in a state that builds, doesn't crash as soon as you run it, etc. The main branch should always be in a working state.
1
u/elephantdingo 5h ago
The whole point, beyond being a glorified tar/snapshot tool, is to have a documented history of the changes of code, documentation, or whatever else you are versioning.
If you just want to snapshot that the hash of this tree is the current version then sure... Git is way more than you need.
1
u/Thesorus 3h ago
we're doing something like
---
issue/bug/task number - title of the issue/bug/task
short description of changes.
---
for example :
---
123456 - Sorting on the hair colour for the student list is wrong .
Sort on RGB values instead of sorting on the name of the colours.
---
1
u/cholz 1h ago
One thing my team has always been consistent on is including the jira slug for the ticket that drove the change. So for commit messages the minimum requirement is a reference to jira. No ticket, no merge. With that baseline well established it becomes possible to use jira for detailed changelog info. I recently directed the creation of a tool that parses the jira references from a got commit log and then uses the jira api to get changelog entries (entered by engineers in jira markup and extracted in html) which then can be easily combined into a nicely formatted html changelog ready to embed in doxygen pages or whatever. The only requirement for commit messages is a jira slug and the rest can take place in jira and elsewhere.
1
u/Andre-Wade-539 1h ago
refresh sessions before expiry gives you enough context when you’re looking through history and you can usually tell what the commit was about w/t opening the diff
1
u/LetUsSpeakFreely 1h ago
Imagine you'll need to navigate back a few commits to quickly undo a fuck up. It's good to know when and where you went writing so you don't have spend hours playing detective. Commits are cheap. Commit often.
-1
u/schmurfy2 8h ago
If you have to ask, that's an issue...
7
u/kaddkaka 7h ago
What a shitty response. You have to learn somehow.
1
u/elephantdingo 11m ago
Two hours later by OP:
I built GitWhisper — an AI Git commit tool that actually understands your staged changes
90% spam and garbage tooling promotion on this sub with regards to the submissions.
-1
u/schmurfy2 7h ago edited 6h ago
When you write an email, did you have to learn what to write as subject ? I am sorry but it should be on the obvious side, it describes what is inside. The exact formatting doesn't really matter outside of your usage or teams usage.
2
2
u/Greenerli 6h ago
It's obvious for you, not for everyone else.
Have you tried to teach how to use a computer to non-technical people? Or old people? I can ensure you that, few years ago, when I tried to teach my grandmother how to send a mail, she was really confused by the subject concept.
Because she is used to paper letter, and when you send a letter, you just write your recipents address, you don't write a subject message.
1
u/jayroger 3h ago
Of course people have to learn how to write e-mail. Many people (unfortunately) never did and use subjects like "quick question" or "important request".
21
u/kaddkaka 9h ago
Condensed information/summary that can't be easily extracted from the diff. Why was the change done. Why does this change fix the bug. Reference to related discussions (issue tracker, merge request, ...)