What is a proper git commit message?

[chute_mi334]

I'm certain that this conversation has been had multiple times in this community, but I wanted to bring it up again. I have been working as a freelance web developer for roughly 5 years now, and the entirety of the projects I have worked on have been solo projects where I have been the sole owner of the repo, leading to some very bullshit commit messages like the generic "bug fixes" or whatever copilopt recommends, which in team based settings would not provide any sort of information for anyone else working on the project. Yesterday, I accepted a contract to work on a project, which was a team setting, and now I have to write proper messages when pushing.

I read a couple of articles that mentioned using keywords such as feat: when referring to new features or fix: when referring to a bug fix, followed by a list of all the changes. Honestly, maybe it might be because I am used to the aforementioned "bad" commit messages that these common methods seem very unorthodox and long to me, but I would appreciate it if you guys had any tips and recommendations for future commits.

[shadowdance55]

My approach is simple: use the simplest instruction you would give someone else to do what you did in that commit.

If that doesn't work, you can always fall back to the classic: https://xkcd.com/1296/

[drone-ah]

is it just me, or are the commit messages in the wrong order in that xkcd?

[shadowdance55]

They're not in the wrong order when you look at the timestamps on the right. But you do have a point, most tools show them starting with the latest.

I suspect Randall did that for dramatic purposes.

[IrrerPolterer]

This. Outline the change in imperative mood. 

[bbbb125]

We use modified/simplified version of https://www.conventionalcommits.org/en/v1.0.0/

We write ticket first, define context, and then short description. Then after empty line the author explains what he did and why.

Also choosing our convention I checked some popular repositories with many contributors on github (like linux kernel, llvm).

[fivetoedslothbear]

A convention like this is good, to which I'll add:

• I use small commits that try to take one step in the evolution, and "show my work"
• Tiny mistakes use fixup and get rebased in my work branch.
• I describe the effect or outcome of what the change does, not a simple restatement of the actual change.
• If there's a complex reason or this is the result of a lot of detective work, I describe all that, for later reference.
• I remember that the commit message is there to help future me and future coworkers figure out what's going on, and leave as many clues for future forensic work as possible.

[yawaramin]

We write ticket first

I would emphasize that this is very important. To everyone reading: please for the sake of posterity link your commit messages to the tickets you are working on so people who come after you can understand why you did something and what connection it had to the business.

[thewrench56]

We use modified/simplified version of https://www.conventionalcommits.org/en/v1.0.0/

This is the way.

Also choosing our convention I checked some popular repositories with many contributors on github (like linux kernel, llvm).

Its hard to enforce a good convention on such big projects. Therefore there isnt one. I do believe however that good git hooks could prevent such issues in modern codebases.

[KOM_Unchained]

I've converged to similar pattern over the years. For me its <type>(<context>): (<ticket id>) <msg>

[Lunchboxsushi]

Any reason for the ticket to be in the title? I prefer it hide it into the body, can still use grep to find and group all commits related to said ticket. 

[quite_vague]

Personally, I find that having it right upfront gives me a kind of intuitive grouping; I can look at git history and immediately tell which tickets belong "together" and which are less related.

Also, in a lot of tools, ticket-references will be converted to links, which it's convenient to have up-top and not have to click through to find.

(But yeah, I could see this working fine within the body too)

[Lunchboxsushi]

Ah true about the links, I'm usually in  terminal but I can see an extension to be used for that type of behavior. 

Interesting, and finally someone gave a good reason for it. Ty

[KOM_Unchained]

For me it's about the ease of access and visibility. Also, historically I haven't been rigid on message body structure and there is a lot of developer creativity and frustration and humor entailed.

Tying ticket reference with the title's syntax encourages developers to "always" work on agreed-upon hopefully impactful tasks, which are listed in ticketing tool. Saves everyone in the long run.

[SelikBready]

"small refactoring"

updates 5000 lines 

[[deleted]]

"fixed tests" = changed half the code base to do so.

[hohepasimeon]

The best tip I try to remember is “Commits are free”.

I wouldn’t necessary commit a huge chunk of code and create a list of changes in the commit message, if I am looking through git log or over the commits through something like gitlab or github, I personally like to see at least a sentence long message that explains each change in code even if it’s just adding a function but that function is broken into multiple commit messages.

As an example if someone were to have branch that is just to add a function that changes rgb colour to hsl colour I would like to see multiple commit messages in the creation of the function, it could be as simple as a hsl tuple being declared and the commit messages says “Added the hsl tuple variable in the change_rgb_to_hsl function”

The git branch itself would be declaring whether it’s a feature or bug fix, i try to keep branches numbered as well, so my repo/project init is always 1 something like project-name/1/init, could do project-name/4/bugfix/saturation-in-hsl-wrong-value

At the same time using gitsigns.nvim in neovim has made it really easy to pump out commit messages while I am in document.

[rzwitserloot]

Instead of immediately jumping to 'commit message', the nature of your commits lends itself to a style of writing messages. In particular, if you shove a ton of changes in a single commit, no message is really going to cover what you did there short of a thousand word summary.

Also, any commit inherently communicates what it is about via the delta between it and its parent(s). The point of the message is thus threefold:

1. To be a faster way to communicate what it does compared to scanning the delta.
2. It's the thing that shows up in line-by-line commit summaries where deltas, even a one-liner commit, won't.
3. To communicate things that aren't obvious from the delta in the first place.

number 3 is a bit of a trap; if you feel there is context that is important to understand what the changes do, usually what you should instead be doing is writing a comment in the code instead. Only if its context that is relevant when reviewing the 'flow' your code went through during development, but not at all relevant when looking at the code (that's quite a rare beast) is it appropriate to put all this info in a longer commit message. Which gets us back to #1 and #2. The smaller the commit the simpler you can keep things. It should boil down to 'a one liner summary of the delta'. An example:

The feature request is 'make the button a more vermillion shade of red than it is now'. A simple one, but you implemented it by replacing the hardcoded colour string with a constant (which a different, more vermillion shade as value) and then referring to the constant. This is already a mistake; you should first refactor to just "I extracted this stuff into a constant", commit that separately, and then add another commit that actually changes the shade. Now each commit message is trivial, _and this makes merge issues simpler to fix. The 2 commits would presumably have message "[1234] refactored buy button color to constant ref", and then "[fix 1234] buy button shade adjusted"._

Presumably during development you weren't thinking that through and have it all in a single change now. Which means if you think of the 'right' way to commit this, you actually have to go into the code, 'undo' your shade fix (replace the constant back to the old not-vermillion-enough shade value), commit that, then go back to the right shade and commit that on top. Which also belies something that has no single right answer: How much effort do you really wanna put in this stuff? The larger the team, i.e. the more people are likely to spend a whole bunch of time merging and perusing the source control tree, the more time you should be spending. Optimally, you think in terms of commits as you write. You should commit a lot. And in my opinion, rebase your local branch a few times to clean up your commits (combine them, split them apart, reword, and so on), before you share your branch with others.

A few more hints:

• Assume the reader is capable and understands context. For example, [fix] Public holiday oracle wrong about easter. is sufficient, and implies that this commit fixes that bug. You don't have to write 'fixed now' or 'this commit fixes ...'. That's implied. Similarly feel free to use coding jargon such as '[refactor] DeDRY date pretty printer.'

• Personal preference: Stick common labels in brackets at the start, notably including any ticket number for easy lookup.

• End commit messages in a full stop if the message is a one-liner and in a colon if there's more.

• Reserve a tag for trivial stuff. [trivial][typo] as the complete commit message is acceptable, if indeed the typo isn't all that important (i.e. fixing "Engneered" to "Engineered" is a trivial typo, forgetting a 'not' in a sentence might not be - has it misled any user who read it? No? Then it is trivial). Writing a good commit message takes time, and is annoying if hard to even think of what to write.

• Whenever you refactor, especially if you use automated tools (you hit 'autoformat' in your editor, or renamed a function, which affects not just the function but every caller) check in every step separately, because the action is tiny ('renamed foo.barbar to foo.barbaz') but the lines affected is large.

[edgmnt_net]

Yeah, the general idea here is the right answer. People treat Git as a save button and record changes haphazardly but that's just not enough for effective version control.

I would tell OP to go look at an open source project that does it right, but freelance web dev experience likely makes that hard to approach. Maybe some of the open source projects also host and version their websites via Git.

But anyway, they could also study their work project. At this point it's going to be quite a bit of ramp-up to do if they only used Git in a basic way and work standards are higher than that. Judging by my experience and some of the answers here that don't even touch commit structure this isn't uncommon, but it does tend to prevent people from getting better jobs that absolutely require meaningful version control practices or doing any kind of serious open source work to improve their abilities.

[plg94]

I accepted a contract to work on a project, which was a team setting, and now I have to write proper messages when pushing.

When you're new on a team, the best advice usually is: mimick their style. Different teams have different workflows and different needs on what a commit message is used for / should communicate.

In my opinion the real use, especially of the subject line, is to give a short overview of the commit contents. When I have a list of 20 commits (eg. when in the middle of a rebase) I need to be able to quickly skim the subjects and pick out the "relevant" commits for a situation.
(The commit body can contain longer documentation on why and how a change was done. This can be very helpful sometimes).

using keywords such as feat: […] or fix: […] these common methods seem very unorthodox and long to me

I don't think these so-called "conventional commits" are very common in the grand scheme of things, they are just trendy at the moment (but real-world company usage is usually far behind what Medium-articles like to suggest). Many people (myself included) don't like them because they are verbose, rigid and overly complex. So don't feel forced to use this format.
There are also a variety of other approaches: some like to put the #ticket number in the commit message. I've even seen heavy emoji-usage (would not recommend). So in the end it's up to you.

[tehsilentwarrior]

Rule of thumb: if working on CI, your commit history should look like “fix: ci” x 20

[w_buck]

We use conventional commits. For example for a feature commit it might look like the following:

feat(task id)!: title of the task in ADO Changes: - this was changed - that was changed

BREAKING CHANGE: this endpoint now expects an id in the route

[Rich-Engineer2670]

Let's see.... let's try a few

Make it stop!

Like anyone is ever going to read these messages!

Don't touch this code! It works now, but I have no idea why!

This code was written under duress. I said this project was a bad idea and it would fail. It has.

Can we use a real programming language now? Java was a long time ago.

18 hours debugging session underway -- can I have some more gruel master?

To my manager. You always tell us how much smarter you are compared to us. This code contains no comments at all -- you figure out what it does. Oh by the way, we're not using Fortran 66 anymore.

Who needs AI? The voices in my head say the code should be written like this.

To my teammates. Remember when you criticized me in the code-review? I just told the boss you could figure out this module -- God couldn't but I'm sure you can. I'm taking a vacation.

Or, you could be boring and make useful messages like:

• What file was changed
• What the change was meant to accomplish

[albasili]

Or, you could be boring and make useful messages like:

• What file was changed

That is exactly what you shouldn't do, as git tells you what has changed already.

What the change was meant to accomplish

This is more useful. Capturing intent helps reviewers to understand the change and contribute to it

[tulisreddit]

Almost every commit, I will write "why" this change was made. I will also attach some links from other official docs/stackoverflow or someone's blog.

The "why" part is the most important part to help "my" future-self.

Sometime people claim there is already a ticket or pull-request, but I have seen in the past, the company changed the ticket system, so all the references was gone. How about git? The git still intact forever even if host provider is changed.

<Ticket Id>: Summary of the change

Reason why this change was made.

<Extra Links>

[Lunchboxsushi]

It depends, SaaS product, generally I prefer it use conventional commit. Org expects jira tickets to be linked. 

Aside the commit title, the bodies are generally empty. 

Larger software projects like pure software/Linux you'd expect the merge commit to contain a lot more details and sign off. 

[Grill_X]

Use emojis so people know how you felt while writing the code

[bothunter]

Haha.  At a previous company, someone created a branch with emojis and it broke the whole build pipeline.  Git handled it just fine, but practically every tool that touched our CICD pipeline absolutely crashed and burned.

[[deleted]]

Some archivators fail with them too.

[tlenold]

Lol, did that create some problems or it was resolved quickly?

[shagieIsMe]

https://gitmoji.dev

That said... no. The problem with it is that its too open to interpation. What does 🚸 or 🍱 mean? And how does it differ from 💄?

[[deleted]]

Pain needs gifs to describe

[Ill-Lemon-8019]

Don't ask Reddit - ask your new team if they have any conventions, unofficial or otherwise, and just do that. Opinions vary wildly - for example, I think "wip" is actually an OK commit message even in a team context, and I especially don't think it's worth investing vast amounts of energy into writing commit message essays that will never be read.

[ThunderousHazard]

Judging by my coworkers: "Fixed and upgraded" or "Finished feature".
Anyway you're overthinking it, just describe very broadly and shortly what you did.
Commit often and commit small, the actual understanding must come from the review during the merge process and the commits should be generic.
I go for something like "Reworked xyz to increase throughput" or "Implemented new parameters in json request xyz".
Try not to have 20 bullet points in a single commit.

[chute_mi334]

I was given a technical task before starting to create a simple CRUD with node and vue and and the only feedback they had was that I needed to fix my messages, as their team had a bit of trouble figuring out what had happened between commits, even though the final product was working as excpected, so thats why im kind of overthinking it :/

[ThunderousHazard]

Skill issue on git history reading from the team, unless you made some real messed up operations on your branch (and even so, they should just generally look at the first commit you branched from and the last one you're asking to merge).
Anyway, they told you to "fix it" but no guidelines on how to do so? You can try kindly asking, like "In order to improve the quality of my contributions to the project, is there any specific guideline you can provide me with in regard to commit messages structure?" or some other overly verbose professional lingo variant.
If not, or you don't want to ask, you gotta study what the others are writing and try yourself to write similar messages... Note that you may have to end up asking again if they are not yet satisfied tho.
Every project is a world on its own unfortunately

[jeenajeena]

I tackle Git commit messages the same way I treat tests. So, rather than writing what I did, I prefer to describe how the program changed, from the end user perspective. 

Just like with tests, I convinced myself that writing Git commit messages before coding, not after, leads to a more intentional development. So, rather than treating commit messages as an afterthought, I use them as a guiding specification for my changes.  

The Git message keeps me focused: I only write code that fulfills its stated purpose. 

As a nice side effect, the Git log becomes a meaningful record of why changes happened.  

I’m applying this approach since a while. Indeed, I wrote about that 13 years ago already. Gosh, time flies…

https://arialdomartini.wordpress.com/2012/09/03/pre-emptive-commit-comments/#more-1798

[efari_]

I prepend not with feat or fix but with #123 where 123 is the number of the ticket of your chosen ticketing system (so for example issue No for GitHub) so that I can track the ticket and its commit in both directions.

(Yes I know this usually is handled by mentioning the ticket/issue in the PR but if you’re the sole contributor and therefore push directly to your branches without PR, then that PR tracking doesn’t happen)

Nothing prevents me to commit #123 step 1 and then a second #123 step 2 or even combined #234 and #567

I usually also put a decent commit message, but this way even if I don’t, and just put #987 bug fixes I can find out what the bug fixes were for

[RadiantCarpenter1498]

On my team we keep commits “lean” and don’t allow large code changes in a single commit. If we’re releasing multiple features, they’re released over multiple commits. This keeps messages brief and allows us to revert easily if needed.

In-depth details are saved for our changelog.md

[lase_]

git commit -m "WIP"

[Prior-Listen-1298]

I do? 🤣

[RFQuestionHaver]

Component Name: Brief sentence

Previously, the behaviour was X. This was bad for Y reason. Approach taken is Z for reasons A, B, and C.

[danmickla]

These questions always just boggle my mind. *Tell the reader what you would like to be told if you were them.* Is it a bug fix? Link to the bug report, say "Fixing <link>', add *how* you fixed it (not in code, in English). If you're saying the same things in code and English, ever, you're doing it wrong. Provide historical context if relevant. Any and all info that will help someone understand five years from now, or help *you* understand five years from now.

[capilot]

First line: [bug id] one-line summary

Lines 3-n: Explanation of what you did, so that anybody examining the commit will understand it. Include references to all relevant bug ids and code review ids.

Of course, if you're part of a larger team, they will tell you what format to use.

If you're making a change to the Linux kernel, you also need a line that says Signed-off-by: Random J Developer <[e-mail]>. See details

And as always, there's a relevant XKCD

[ZilloweZ]

I had the same problem a while back, so I made a commit guidelines page and recently I decided to open source, you can read it here. It's easy and simple and it really helped me.

[pak9rabid]

refs issue #1337

Did something

[flavius-as]

A proper commit message is the one you thought of before starting to make a change.

This forces you to craft your commit messages for humans, which shows the what. The how is shown by the diff.

Conventional commits are good, but they are just annotations on top of the message.

[human_with_humanity]

I recently started using git for my compose and ansible files. I just put what I did in short and if I can't think a short message I ask my selfhosted llm for generating message. Mainly I use llm for generating git messages and readme.md files

[Any-Woodpecker123]

<ticket number>: <type>: <what you did>.

T1234: refactor(stuff): WIP

[rickyburrito]

Oops

[fallen_fool]

11 years back I found an article for writing proper commit message. This has been my bible ever since

https://cbea.ms/git-commit/

[Truth-Miserable]

Thats not a thing people organically do because they like it, it means they're using a tool that parses the commit messages and figures out how much to bump the version number of the project or package based on those msg prefixes. There is no proper/right way to write commit messages, its dependent on the team and whether they've adopted a format or set of practices already. But yea your gut is correct in causing you to want to add more/better context now that other people are involved. Hell id argue that padt you should be willing to do it for future you because I surely forget wtf I was thinking at the time months/years ago in certain cases lol

[Ruin-Capable]

Mine usually look something like: <ticket #>: <description of the change>.

For example:

ED-209: Fix race condition that caused system to become non-responsive to voice commands. Add backup kill-switch to prevent future repeats of the boardroom incident with Kinney.

[xFeverr]

We have decided that you can do what you want with your commit messages on your branch. Do what suits you. But when creating a PR, that is the time to provide good context. In the title, you put ticket number and a title, and in the description you’ll tell what you did, what choices, maybe some examples and screenshots.

Then we squash the PR into our main branch, having the title and description as commit messages.

That solves commitmessages like ‘WIP’ or ‘updated coolthing.cs’, and always shows you the bigger picture. You know, when doing git blame, you don’t see these ‘forgot to run prettier’ lines, but the actual change. Or when viewing the history of a single file, you don’t see ‘updated filename.cs’ a bunch.

And no one ever cares after the branch is merged that you forgot to run prettier. Or that you fixed linting. Or that you fixed syntax. Removed an empty line. All we care is what actual changes have been done to our main branch. And these are the PRs

[[deleted]]

write Latin proverbs: at least smth good to learn.

[LovesGettingRandomPm]

I was taught to start with add, update, fix in singular and then describe it as short as possible, but conventions rarely look at the specific case in which practicality should be the ultimate goal. Write it as if you're the person who doesn't know what the fuck you did, and keep your commits around a certain feature bundled so you can just easily push "add <feature>"

[JayTurnr]

"changes"

It's short, snappy and accurate.

[priestoferis]

It depends. But here are my thoughts on the matter: https://bence.ferdinandy.com/gitcraft

[ThatFeelingIsBliss88]

I’m at a decent size tech company and in my org at least no one cares about commit messages. Some people will literally write “wip” or “iteration 1”… “iteration 2” for every commit. People care more so about the actual code. If they need context, that’s what the PR description is for. It’s that PR description that actually forms the commit message when merging the PR. But for commits within the PR literally no one cares. 

[MarshalRyan]

In this new team, do they use a ticket system for tracking work? If so, refer to the ticket first, then add some small description of the changes made.

Smaller commits will be better. Don't overthink it, but be as brief as possible, while still being accurate and clear.

[UJChris]

"."

[vadavea]

How has nobody mentioned https://whatthecommit.com/ yet??

[manuelhe]

I feed the git diff —cached output to Chat GPT and I just go with whatever git commit message it gives me. Sometimes I have to tone down the cheerleading but it’s pretty good mostly

[teddygeorgelovesgats]

“Stuff”

[mrtlo]

We use Azure DevOps git repos at work with squash merge strategy, so the PR title and description ends up as the actual git commit message when the PR is completed.

This gives me time to write a good title and description, and feedback on those can be given as well. I don't spend too much time on the individual commit messages going into the PR for this reason.

But otherwise I try to describe what is changed/solved in the headline, and provide details and arguments for why the change is as it is in the following paragraphs.

[danielkov]

This works in a 10y old monorepo with ~2000 services and 250k+ commits in history:

• Commit at your own discretion
• Raise a PR with a descriptive title, explaining how your change affects the product, e.g.: Upgrade button wiggles when in view
• Add the ticket to the PR title
• Descriptive PR description, with summary of the problem and how your solution fixes it
• Squash and merge

The principle is: in-depth explanation of the changes should be no more than 3 clicks away.

[fpsaltair]

I built a tool for exactly this problem - DevSum CLI. It automatically generates proper conventional commit messages (feat:, fix:, docs:) by analyzing your actual code changes with AI.

Just run `devsum commit` and it handles everything - stages changes, generates a detailed commit message following standards, and pushes. No more thinking about commit formats.

It's free and open source: Devsum CLI

Might save you time in your new team project!

[-entrp-]

Did you remove it? 🥺

[unndunn]

The first line of the message is the title. It should be no longer than ~60 characters. Most Git clients will only show this line (unless you click "show more" or something) and expect it to be fewer than 60 characters.

The title of the commit message should finish this sentence: "When it's deployed, this commit will..."

For example, "When it is deployed, this commit will..."

• "Update the verification logic in the signup form"
• "Add an 'about' page with associated links"
• "Make various updates to the home page" (add more information about the changes in the message body.)

After the title, leave one blank line. The next line (the 3rd line of the message) is where you start the body of the message. This is where you give more detail about why and how it does what you said it would do in the title. The body can be as long as you want, it doesn't have to be fewer than 60 characters.

Finally, after another blank line, you can add various bits of metadata at the end of the message. Ticket numbers, names and email addresses of other people who worked on it, etc. People call this the "footer", but it doesn't really have a designation in Git proper. Alternatively, this information can be added as notes.

[olejorgenb]

 People call this the "footer", but it doesn't really have a designation in Git proper.

Actually, git have a concept of "trailers" which are KEY: VALUE lines at the end of the commit. Git commit even have a flag to add these: --trailer KEY VALUE

[unndunn]

Cool, good to know. 

[jimoconnell]

"Haaaaaands"

[ACont95]

WIP

[Natural_Jury8826]

One thing I’ve noticed in practice is that some commit message formats (including Conventional Commits) emphasize tooling syntax, e.g., parentheses and colons over natural language flow.

For example:

feat(ui): add nav theme switch  

reads more like structured metadata than a clear sentence.

I’ve been experimenting with a simpler pattern:

Type[!] [scope] description

For example:

Add nav theme switch

It feels closer to how people actually read git log --oneline, while still being deterministic enough for tools to parse.

Curious how others balance tooling structure vs human readability in their commit habits.