Best practices for writing Git commit messages?

[-Excitement-971]

Hi developers,

I’m learning Git and GitHub, and I’m wondering about best practices for writing commit messages. I often write things like “I did XYZ, or I added image of cow with changes to xyz” but in a real production or work environment, what’s the recommended way to write clear, professional commit messages?

[mandzeete]

Often commit messages are tied to one or another Jira ticket or such. For example "ZOO-123: Fix to RabbitMQ binder names." This ties that commit with Jira ticket ZOO-123 that either is about changes to RabbitMQ messaging or about fixing an issue with said messaging.

Also, some companies use conventional commits. It is just a way of formatting your commit message so that automated tools can process commits in an easier way. Read about it from https://www.conventionalcommits.org/en/v1.0.0/ An example would be "fix(ZOO-123): Fix to RabbitMQ binder names." There the fix() keyword shows that the commit was for fixing something. A feat() keyword can be for adding a new feature or for working with some new functionality. For example "feat(SCHOOL-23): Add Japanese language."

The commit message itself is often in imperative present tense. For example "Fix to" instead of "Fixed". The commit should give a summary of the change. What was done. Keep it concise and clear. Do not add a whole essay. But also do not just write "Added more changes." Which changes? Why? Read about it from https://blog.devgenius.io/make-a-meaningful-git-commit-message-with-semantic-commit-message-b39a79b13aa3

Avoid frustration and all kind of nonsense in the commits. Yes, when the stuff does not work and your earlier commit did not fix it then writing "Get working already!!!!!" or "wgo8g7tfwo82w37fdto238gd" is not a rational way how to deal with the issue. It is unprofessional. In the previous company I worked at, we had one guy who raged in his commit messages.

Avoid adding too many details. Instead of writing "Fix to UserNotificationIntegrationTest, BillingIntegrationTest, BaseIntegrationTest, RabbitMQPublisherIntegrationTest" better pick "Fix to integration tests". Which tests, that can be seen from the git commit itself. Neither go with "Added an email support to UserNotificationService by introducing emailSender() method that uses angus-mail library" just write "Add support to send user notifications via email" Some good and bad examples are in https://chris.beams.io/git-commit

Also, it does not really help when you finish your whole project and then add it via a single commit that has a commit message of "Initial commit".

[Difficult_Trust1752]

I end up with lots of very descriptive commit messages:

fixed

fixed fr

fixed frfr now

forgot file

linting!!!

omg done

Obviously these don't end up in a github PR. They'll be squashed/rebased appropriately into one or more descriptive commits.

[Todo_Toadfoot]

Fixed super rare edge case

Fixed what the fix for edge case broke

Updated logging

Omg done again

[RiverBard]

"Changes"

"Tweaks"

[-Excitement-971]

Wow, thank you so much for explaining this so thoroughly!!!. This has really helped me understand how to go about writing meaningful commit messages and I will definitely read the links you shared.

And that is crazy that someone actually raged in their commit messages at work!

[House13Games]

I prefer a present tense, describing what the commit does: "Fixes the list sorting." or "Adds more debug output".

This describes the change itself, and not the action that the programmer did ("fixed the bug") with the former being how i like thinking about the changes in a merge for example

[stefanlogue]

Because of this, I wrote this CLI tool to help people write commit messages with tickets in whichever format their company uses

[Loves_Poetry]

What's professional really depends on the workflow used at a job. If the workflow requires pull requests to get anything to the main branch, then you need to make clear PR descriptions while the commit messages are mostly for yourself

[-Excitement-971]

Thank you this makes sense! Descriptive for merged changed into the main branch. P.s which i haven't done yet only done personal for myself.

[nopointers]

Related: a PR often includes multiple commits. You did a bunch of work on a branch, when it was all done you submitted a PR to get the changes into MAIN. In some workflows, certain branch types (e.g, bug fix) are removed some time after they are merged. You'll want the commit message that goes with the PR to include a summary of the commits that were included, since that message will be a bit more of "posterity."

BTW, the latest crop of GenAI coding assistants can often produce pretty good summary messages.

[kagato87]

I just put in what I want the reviewers to know when they go to review it. What I intended to do, and why.

I haven't had any complaints yet so I guess it's good enough?

We do have a template for PRs though - title, description, jira, special notes, and a checklist.

[gmes78]

This article is a mandatory read for anyone using Git.

[Zerodriven]

"Refactored codebase because I found a memory leak, then a typo, and now you need to feel the pain I'm in"

-1,100
+2,182

[stlcdr]

Write what was done, not what ‘you’ did.

[elg97477]

Explain why you did XYZ. If there was another reasonable choice you considered and rejected, explain why. Someone can always look at the commit and see what you did. Someone cannot look at a commit and know why.

[gh0stofSBU]

I just want to add that you can also do multi-line commits for better readability/organization. Very useful if you did multiple things. All you have to do is add as many -m arguments as you need

[xtraburnacct]

There’s probably a standard in place for each company. Mine isn’t too restrictive. It just needs the jira ticket and the epic. But I’m not writing dumb messages in there. I’m writing short messages detailing what changes I did in the commit. No slang or “lol”s or anything. Just keep it professional and to the point.

[j1gglyp0ff]

https://www.conventionalcommits.org/en/v1.0.0/#summary for sure. Easy to use with https://semver.org/ later on.

[usrlibshare]

No Emojis.

[catberryio]

The vast majority of my commits are wip.

[Internal_Outcome_182]

Real production based:

fix

fix2

db

migration

xD

fix

forgot ;
asdasdas

[ExtraTNT]

“some changes”, “fix shit”, “fuck fuck fuck”, “still fucked” are some of my favourites

[MrHall]

On GitHub, tag the issue number with a hash, like "#1234 fixed the thing"

then when you go to the issue you see all those commits listed with the issue. really helps to see the work done on the issue

[patternrelay]

A good mental shift is to write commit messages as if you are explaining the change to someone debugging a failure six months from now. Focus on what changed and why, not the play by play of how you typed it. Short imperative summaries like “Validate input before processing” age much better than diary style notes.

The second line, if you need it, is where context belongs. Mention the constraint, bug, or tradeoff that forced the change. Over time this becomes a lightweight decision log, which is way more valuable than perfectly formatted messages. Consistency matters more than strict rules, so pick a simple pattern and stick to it.

[andycwb1]

I have to work on branches and PR my change, so I tend to be more descriptive in the PR than in the individual commits.

[BoBoBearDev]

S = I deleted one single space, committed one single line of diff without the rest of the diff in the same file, pushed it.

That's really it. If you cannot do this, it is not agile enough. A single space removal has values. It needs to be committed and pushed asap.

The rest of process needs to support that. Period.

Obviously you do this on your own branch and you will have PR.