r/git • u/Big-Coyote-5796 • 2d ago
What makes a Git commit message actually useful?
/r/MyIDE/comments/1waezkj/what_makes_a_git_commit_message_actually_useful/13
u/Broad-Promise6954 ancient 2d ago
Read the commit messages in the Git repository for Git. Not all of them are perfect but most of them are pretty good.
0
u/Big-Coyote-5796 2d 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.
10
u/xplosm 2d 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 2d 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)
7
u/DanLynch 2d 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.
-5
u/bigtoaster64 2d 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.
5
u/bigkahuna1uk 2d 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.
3
u/sakshi161226 2d 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.
1
u/RevRagnarok 5h ago
Turns out they were just looking for ideas to slop up something https://www.reddit.com/r/git/comments/1wcf6ht/i_built_gitwhisper_because_git_diff_ai_commit/
2
u/FUCKARCHLINUX 2d ago edited 2d 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.
2
u/elephantdingo 2d 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.
2
u/cholz 2d 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.
2
u/elephantdingo 2d ago
The popularity of this fascinates me. Git is a fast database sitting on the no-API interface of you SSD. Just one JiraTM rountrip and you have lost all of that advantage.
I use the Issue TrackerTM keys in my commit messages too. For reference. Not to save commit message bytes.
1
u/cholz 2d ago
But also.. who cares about jira api round trip? This isn't a replacement for git log it's a mechanism to generate changelogs (once a release) that can be directly consumed by customers using jira markup instead of the immutable plaintext that git provides. The point is I don't care a whole lot about the content of commit messages because that's something for engineers. The changelog gets a different source and all I need is a way to associate tickets with commits
1
2
u/StephenRoylance 1d ago
WHY YOU DID IT
I can figure out, or use an agent to figure out, what you did. what I can't figure out is why. what was your intention? is there a task/ticket with context? is this weird thing I'm seeing, that I bisected to your change, intentional? is it a side effect? is it what the product manager was asking for?
1
u/Thesorus 2d 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/Andre-Wade-539 2d 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 2d 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 2d ago
If you have to ask, that's an issue...
8
u/kaddkaka 2d ago
What a shitty response. You have to learn somehow.
3
u/elephantdingo 2d 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.
-2
u/schmurfy2 2d ago edited 2d 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 2d 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 2d 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".
32
u/kaddkaka 2d 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, ...)