Semantic Commit Messages

semantic-commit-messages.md

Semantic Commit Messages

See how a minor change to your commit message style can make you a better programmer.

Format: <type>(<scope>): <subject>

<scope> is optional

Example

feat: add hat wobble
^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

More Examples:

• feat: (new feature for the user, not a new feature for build script)
• fix: (bug fix for the user, not a fix to a build script)
• docs: (changes to the documentation)
• style: (formatting, missing semi colons, etc; no production code change)
• refactor: (refactoring production code, eg. renaming a variable)
• test: (adding missing tests, refactoring tests; no production code change)
• chore: (updating grunt tasks etc; no production code change)

References:

• https://www.conventionalcommits.org/
• https://seesparkbox.com/foundry/semantic_commit_messages
• http://karma-runner.github.io/1.0/dev/git-commit-msg.html

Code-only "features"

What about "features" that add functionality to the code base, but aren't anything that the user of the application cares about?

Example addition:

funcs = []

def register(f):
    funcs.append(f)
    return f

"""
Now the developer can register functions... yay!

@register
def say_twice(s):
    return f"{s} {s}"
"""

This change helps only the developer in the future. The user is not affected at all. What is a good commit message?

feat: add function registry decorator

This omits the use of !, such as feat!(auth): require two-factor.

The ! after a type indicates that it may be a breaking change or is otherwise suspect for issues that arise.

Would you also add ! to this document?

thanks :)

I still have doubts when to use the chore, can someone explain to me?

@AJohnsoon I would think that is the scenario which all others scenarios does not fit. I would think as a dependency upgrade. But to create a hypothetical use case.

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Example taken from: https://www.conventionalcommits.org/en/v1.0.0/

@dheysonalves oh, thanks for help !

thanks

thanks @joshbuchea
and thank you also @JohnnyWalkerDesign

Why everyone use 'add' and not 'adds' to the commit message? Looks to me that the hidden subject is 'It'. E.g.: 'It adds something'.

Sorry if it's a silly question. I'm not a native English speaker.

@ralphwbms It's what the Git documentation specifies as the standard: Present tense.

Update: Oops. I meant "imperative" not "present".

Great commit messages will adhere to several "rules". Rule 5 of https://cbea.ms/git-commit/#seven-rules states:

Use the imperative mood in the subject line

And this is backed up by a lot of material, just look through the various links above the listed rules. I do recommend that you read the whole of the Chris Beams article as well as David Thompson's article on helping to improve your commit messages. These, along with the semantic / conventional commit message really improve commits!

@ralphwbms Similar to a function name, the commit message describes not the action itself but how the data is modified (in this case the data is your code). Think of a commit as a building block so that you can read through the commit history like a recipe (or a pseudo-code).

@JohnnyWalkerDesign , @tykeal , @guneyozsan

Thanks everyone for the tips and quick answers 😄 I will definitely check them out.

I've been using the correct patterns for commit messages for some time now, but I've never understood why the verb doesn't have the 's' at the end, as we are giving an order (imperative form) to a thing (Git), which implicitily is a 'It'. But I just realized that when we give an order to a thing in English, we also use "you", and not "it". So, the subject doesn't change as I thought, It keeps being 'You'.

Sorry for the confusion guys. But talking about it made me finally understand WHY 😄

Suppose I follow semantic commits and later on we have a squash strategy for merge, then semantic commits make sense?

My personal take on this is that if you're doing semantic commits, then you really don't want to be doing squash merges as you will lose context. Squash merges are in general best for dealing with cleaning up a series of crap commits.

If you're following good commit practice, then every commit is atomic to your needs. I go out of my way to make sure that as I'm developing each commit is literally the barest minimum for a single modification (bug fix, feature, docs, etc). I even do my refactoring this way. I only refactor one thing at a time per commit. Yes, it makes for a lot of commits, but smaller commits are easier to code review anyway!

which type should I use if just changing a field?

for example:
String url = "https://www.aaa.com";
change to
String url = "https://www.bbb.com";

refactor？

@Loyea seems like "fix(part): set new url"

@Loyea @Mauzzz0
hmm.. context is important.

feat

• api change v1 -> v2

---

fix

• typo httpp:// -> http://

---

test

• http://localhost -> http://real.com

The example instructs us to write "Summary in present tense." but it's not the present tense that should be used but imperative.

• present tense: "[pronoun] add(s) hat wobble"
• imperative: "add hat wobble"

What type of commit should I use to add functions that are already common in the application? For example a Logger. Should it be feat ? Hmm I doubt it

thanks info

Thanks 😊

Pls tell this to Shakhriddin

The example instructs us to write "Summary in present tense." but it's not the present tense that should be used but imperative.

• present tense: "[pronoun] add(s) hat wobble"
• imperative: "add hat wobble"

Yes, you are completely right. It's imperative, not present.

What's your take when marking something as obsolete (but not deprecating yet)?

I would say either refactor (no substantive change) or chore (as it's a chore to do deprecation notices :D )

What does doc mean?

What does doc mean?

I'm assuming you mean docs. In our projects it almost always means changes to README.md.

I doubt what should be the commit type for adding the GitHub workflow for PR title check,
Can someone please suggest ?
@dheysonalves, @coolaj86 , @markushav, @tykeal

I doubt what should be the commit type for adding the GitHub workflow for PR title check,
Can someone please suggest ?
@dheysonalves, @coolaj86 , @markushav, @tykeal

Since tweaking a GitHub workflow probably would not touch application code I would use ci: or chore:.

First thing I always ask myself is: Does the commit affect users and therefore requires any kind of version release? If the answer is No then fix: and feat: are out and I pick the most appropriate option left.

I doubt what should be the commit type for adding the GitHub workflow for PR title check, Can someone please suggest ? @dheysonalves, @coolaj86 , @markushav, @tykeal

I would go with CI: for something like this. It's purely dealing with CI processes. I hold Chore: for things like cleanups of deprecated bits, or bumping versions of things. Basically, if it's something a bot could have done for me it's likely a Chore: all my pre-commit hook updates are labeled this way and not CI: even though they effect CI.

Just out of curiosity. What type should be for release commits?

I still have doubts when to use the chore, can someone explain to me?

I think it's for things like rebuilding package-lock, bumping version when dependencies are patched, stuff like that.

I have no use for the style type. For formatting fixes I'd put that under chore or refactor depending on the severity of the formatting fix.

What about enhancements? I.e. making a few things better in the UI so it becomes easier for the user, or when updating translations to give better information to the user. It's not really a feature, because it doesn't bring something new to the table. It's also not fixing something, it's just improving something.

Anybody can help?

Edit: Join the discussion at conventional-commits/conventionalcommits.org#78

What do you guys think of capitalizing the types?

Refactor: making debug print prettier

@weiying-chen Absolutely against it, one more key to press. Plus, if you capitalize the first letter, you also have to capitalize the first letter after :. All lowercase makes my life so much easier.

@weiying-chen Absolutely against it, one more key to press. Plus, if you capitalize the first letter, you also have to capitalize the first letter after :. All lowercase makes my life so much easier.

I see, but you don't have to capitalize the letter after :. It's proper grammar/style.

@weiying-chen Oh yes, British English rules came into my mind once again. Still like the consistency of lowercasing everything, except for acronyms or names.

I see. But if we are talking about consistency, one could argue that since comments in code are capitalized, it makes sense to capitalize git messages. For example: // TODO: make debug print prettier git commit -m "Refac: make debug print prettier"

…

On Sun, Feb 12, 2023, 11:11 PM Martin Braun ***@***.***> wrote: ***@***.**** commented on this gist. ------------------------------ @weiying-chen <https://github.com/weiying-chen> Oh yes, British English rules came into my mind once again. Still like the consistency of lowercasing everything, except for acronyms or names. — Reply to this email directly, view it on GitHub <https://gist.github.com/6f47e86d2510bce28f8e7f42ae84c716#gistcomment-4468494> or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIDC5JSHAORRZKCU5NAKJLWXD4RDBFKMF2HI4TJMJ2XIZLTSKBKK5TBNR2WLJDHNFZXJJDOMFWWLK3UNBZGKYLEL52HS4DFQKSXMYLMOVS2I5DSOVS2I3TBNVS3W5DIOJSWCZC7OBQXE5DJMNUXAYLOORPWCY3UNF3GS5DZVRZXKYTKMVRXIX3UPFYGLK2HNFZXIQ3PNVWWK3TUUZ2G64DJMNZZDAVEOR4XAZNEM5UXG5FFOZQWY5LFVA2DONZRGE3DCNVHORZGSZ3HMVZKMY3SMVQXIZI> . You are receiving this email because you were mentioned. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub> .

I'd say the commit type is more like an enum:

enum Type {
  feat,
  fix,
  docs,
  // etc.
}

Thinking like this, semantically maybe the type should be capitalised, or even all upper-case? You could also imagine the types to be like the keys of a JS object, and then you'd be convinced they should be camelCased!

I find capitalisation in commit messages to be frivolous, but as long as you're consistent, feel free to enforce your own style. Lower-case is simple.

I'd say the commit type is more like an enum:

enum Type {
  feat,
  fix,
  docs,
  // etc.
}

Thinking like this, semantically maybe the type should be capitalised, or even all upper-case? You could also imagine the types to be like the keys of a JS object, and then you'd be convinced they should be camelCased!

I find capitalisation in commit messages to be frivolous, but as long as you're consistent, feel free to enforce your own style. Lower-case is simple.

Enums in Rust are caplitalized:

enum ThingsInTheSky {
    Sun,
    Stars,
}

https://dhghomon.github.io/easy_rust/Chapter_25.html

And I think types are capitalized in both TypeScript and Rust?

Also, I think capitalization in commit messages was the original formatting?

$ git commit -m 'Initial commit'

https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things

My point was anyone can put an argument for any kind of casing with the right abstraction, whether it be correct grammar, enums, object keys, etc.

This also applies to the origin argument:

Also, I think capitalization in commit messages was the original formatting?
$ git commit -m 'Initial commit'

Which is arguably the most compelling argument for capitalisation, but I still wouldn't read into this too much because the commit syntax on Linux is very loose, and so Linus Torvalds hasn't seemed to think about commit capitalisation as much as you :) e.g.
https://github.com/torvalds/linux/commits/master?after=f339c2597ebb00e738f2b6328c14804ed19f5d57+104&branch=master&qualified_name=refs%2Fheads%2Fmaster

I maintain:

I find capitalisation in commit messages to be frivolous, but as long as you're consistent, feel free to enforce your own style. Lower-case is simple.

My point was anyone can put an argument for any kind of casing with the right abstraction, whether it be correct grammar, enums, object keys, etc.

This also applies to the origin argument:

Also, I think capitalization in commit messages was the original formatting?
$ git commit -m 'Initial commit'

Which is arguably the most compelling argument for capitalisation, but I still wouldn't read into this too much because the commit syntax on Linux is very loose, and so Linus Torvalds hasn't seemed to think about commit capitalisation as much as you :) e.g. https://github.com/torvalds/linux/commits/master?after=f339c2597ebb00e738f2b6328c14804ed19f5d57+104&branch=master&qualified_name=refs%2Fheads%2Fmaster

I maintain:

I find capitalisation in commit messages to be frivolous, but as long as you're consistent, feel free to enforce your own style. Lower-case is simple.

Yeah, I agree. It's probably not that important. Maybe I'm being too OCD here.

But in my original post, I just wanted to know what people thought of it.

My team holds to the 7 rules of commit messages espoused by Chris Beams. Rule 3 states that the commit subject line should be capitalized. We treat it for the topic as well as the first char after the :. Since our commit messages are all English, it makes them easier to parse because of how English is constructed.

My team holds to the 7 rules of commit messages espoused by Chris Beams. Rule 3 states that the commit subject line should be capitalized. We treat it for the topic as well as the first char after the :. Since our commit messages are all English, it makes them easier to parse because of how English is constructed.

What's the reason for capitalizing the first word after :?

More a hold over from our commit message enforcement from before we started using topics. It helps keep the message history looking more uniform and clean.

We hard enforce the capitalization of the topic using a gitlint pre-commit hook, the capital after : is a weakly socially enforced at this point.

@weiying-chen Let's have a debate, shall we? :)

I see. But if we are talking about consistency, one could argue that since comments in code are capitalized, it makes sense to capitalize git messages.

I only capitalize comment blocks, because they reflect a paragraph containing sentences, I do not capitalize short summaries, i.e.

local cf = io.open("config.ini", "r") -- load main configuration

My rule of thumb for comments: If it has a dot, capitalize. Do not add dots on single line comments. 2 sentences deserve a block!

For me, commit messages are short summaries and not sentences, thus I strive to keep them lowercase. (Forgot to mention "I" is an exception as well, obviously)

Contrary to this statement, the body of the commit message (if there is one) should be capitalized, here is what I mean:

feat: parallel download updater

The downloader module has been improved to update the database and binary in parallel. 
For this, the database will no longer be embedded in the binary, but downloaded separately.

Workflow:

- Download the recent database if the current is outdated after launch
- Meanwhile check for a new binary and ask for the download if there is one
- Only ask for installing the new binary after all downloads have finished

What's the reason for capitalizing the first word after :?

Grammar rules in other places than the US, btw. The capitalization after : is possible in the US, while it's mandatory in British, thus, if you are formal, you capitalize after : to be inclusive as much as possible.

In regards of "Initial commit" (which is also GitHub's suggestion), I would disagree with applying their example to this discussion, since they don't even have semantic commit messages in their mind. With semantic commits it should be chore: initial commit, if you ask me, since the first commit just uploads code that has been changed multiple times prior. Only from the 2nd commit on changes are documented and part of the commit message, so chore for the first commit feels right to me.

Just because there are counter examples in different areas by bigger companies doesn't mean they are the right source for specific guidelines such as semantic commits that further abstract from git (not even from them themselves).

Finally, all this is nitpicking. I would argue when it comes to collaboration, it's better to be consistent, although I have screwed up so many commit messages by this stage that this is not about perfection for me personally anyways. In a perfect world you find the best practice for you and your team and stick to them for a clean history.

Subjectively, I still think my suggestion is still better, because committing is just faster and it reads very well without unnecessary distractions and less failure potential (i.e. forgot to capitalize). My 2 cents.

I just want to leave a comment saying thank you. As a newbie to all this, I am trying to force myself in the habit of making more meaningful and better commits. This has helped me a lot.
Thank you

What type of commit should I use to add functions that are already common in the application? For example a Logger. Should it be feat ? Hmm I doubt it

chore

@snurfer0 by definition, chore changes stuff that won't change the behavior of the build, like reformatting code or adding stuff around the build tools like helper scripts, etc. Another example is modifying the .gitignore.

In case of adding logger calls, I think feat would be more appropriate. The end-user might not notice the change, but the behavior has changed and the user can still experience that. It's a feature, the app now logs more steps.

https://leanprover.github.io/lean4/doc/dev/commit_convention.html & https://platform.uno/docs/articles/uno-development/git-conventional-commits.html introduce "perf" for optimizations. I think it's a good one

@dpinol Performance improvements make the app faster, which can be considered a feat or fix, depending on the severity. If the app was unusable slow, it was a fix, if the app was fast, but now is faster, it's a feature. Not gonna say it's wrong to pick perf, but I think that is what semantic commit messages boil down to.

It's basically a similar case to tweak. We were thinking that it would make sense, but after a long back and forth, a tweak can also be a fix or a feat, depending on the severity.

I agree with @martin-braun and would say fewer commit types lessen the cognitive load when writing commit messages.

I would also reiterate, "semantic commit messages" are not for everyone. I would go as far as saying if you're not using the type prefixes (feat, fix, etc.) to help automate some other task e.g. releases, generate changelogs, etc., then I would drop them entirely because the types:

• Use up characters in commit messages
  • Devs may then remove detail/meaning from commit messages so their commit heading is under some character limit
• Categorise commits in generic non-helpful ways
  • Worst of all, devs may wrongly categorise changes e.g. using chore when the change is a fix. This problem is proliferated by larger commits which contain chores, fixes and features

Writing good commit messages is hard. But we shouldn't overcomplicate it!

@tobias-edwards The latter part is a real issue in practice. You can often split files to get a fix apart a feat, but it gets very annoying when you have to juggle with hunks. Punishing when not working on separate branches, but sometimes you try to get stuff done in a quick fashion (and sometimes it happens in parallel tasks, oof). I'm guilty of committing files with different changes putting them all under one message as well, we all were at some point.

So yes, committing properly is not easy, but semantic commits helped me to reduce overhead. I agree to all your points.

Thanks. I'm interested in your job position.

…

On Wed, May 17, 2023 at 9:01 PM Martin Braun ***@***.***> wrote: ***@***.**** commented on this gist. ------------------------------ @tobias-edwards <https://github.com/tobias-edwards> The latter part is a real issue in practice. You can often split files to get a fix apart a feat, but it gets very annoying when you have to juggle with hunks. Punishing when not working on separate branches, but sometimes you try to get stuff done in a quick fashion. I'm guilty of committing files with different changes putting them all under one message as well, we all were at some time. So yes, committing properly is not easy, but semantic commits helped me to reduce overhead. I agree to all your points. — Reply to this email directly, view it on GitHub <https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716#gistcomment-4571780> or unsubscribe <https://github.com/notifications/unsubscribe-auth/A4HQZYFABGRMNSAL7Z2PQO3XGVYFZBFKMF2HI4TJMJ2XIZLTSKBKK5TBNR2WLJDHNFZXJJDOMFWWLK3UNBZGKYLEL52HS4DFQKSXMYLMOVS2I5DSOVS2I3TBNVS3W5DIOJSWCZC7OBQXE5DJMNUXAYLOORPWCY3UNF3GS5DZVRZXKYTKMVRXIX3UPFYGLK2HNFZXIQ3PNVWWK3TUUZ2G64DJMNZZDAVEOR4XAZNEM5UXG5FFOZQWY5LFVA2DONZRGE3DCNVHORZGSZ3HMVZKMY3SMVQXIZI> . You are receiving this email because you commented on the thread. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub> .

What prefix would you use for a release branch? feat seems most fitting, but not quite 🤔

@guidotheelen branch names have no commit messages. You can create a branch without a commit. If you mean bumping version numbers and committing that, it's chore, because nothing has changed compared to the last commit.

If you mean to merge all changes of that version into a release branch, you can just use the merge commit that git offers you.

More a hold over from our commit message enforcement from before we started using topics. It helps keep the message history looking more uniform and clean.

We hard enforce the capitalization of the topic using a gitlint pre-commit hook, the capital after : is a weakly socially enforced at this point.

Can share your pre-commit pls?

@DHosseiny here's one of our repositories that is doing this. The pre-commit hook that is enforcing our usage is by way of gitlint (you'll want to see the bottom of the the .gitlint file for our enforcement using capitals) which only runs during the commit-msg stage.

A few questions:

1. What do you prefix changes to build script with?
2. If you're merging a branch into yours, and fixing some merge conflicts on the way, what do you prefix this with?

1. What do you prefix changes to build script with?

CI: (or ci: if you're using the more standard conventions). The reason being that this should be getting exercised by the CI system first and foremost.

2. If you're merging a branch into yours, and fixing some merge conflicts on the way, what do you prefix this with?

Personally, I don't. But I'm working on large projects with stringent code review requirements that require that all changes to code must happen in a standard commit and a merge commit is an empty commit that contains a cover letter at best.

Hello 👋 Please tell me how to write a commit message if we fixed some spelling and grammar errors in the README.md file.

@VinitGurjar

docs: (changes to the documentation)

How to increase MAJOR change? Are there any flag like: git commit -m "major: breaking change"

How to increase MAJOR change? Are there any flag like: git commit -m "major: breaking change"

I've seen in some places the usage of an exclamation mark, e.g chore!: update minimum node version, to signify a breaking change.

How to increase MAJOR change? Are there any flag like: git commit -m "major: breaking change"

I've seen in some places the usage of an exclamation mark, e.g chore!: update minimum node version, to signify a breaking change.

Yes, ! indicates breaking changes. See: https://www.conventionalcommits.org/en/v1.0.0/#commit-message-with--to-draw-attention-to-breaking-change

To remove a commented code, which one should I use? Chore or Style? Or another?

To remove a commented code, which one should I use? Chore or Style? Or another?

I would use chore or refactor, i.e. chore: remove unnecessary comments or refactor: clean up code comments.

Perhaps a lint: would also be useful.
I am including a new ESLint rule to an old codebase.
For the moment, most changes will be about adding ignoring comments for errors which can not be fixed automatically.
But even for the ones that can be fixed automatically I think lint: is a nice prefix.

Perhaps a lint: would also be useful.
I am including a new ESLint rule to an old codebase.
For the moment, most changes will be about adding ignoring comments for errors which can not be fixed automatically.
But even for the ones that can be fixed automatically I think lint: is a nice prefix.

Use chore: since your changes won‘t affect the build.

@phcoliveira The idea of semantic commit messages is that you don't have many options, hence you can pick it properly without much complexity.

@JoaoGH @uncenter chore should be the right one when removing comments. refactor only when you change symbol names, style only when reformatting (removing comments is not part of reformatting).

What would you use for removing an old / deprecated code ?

@oscarwiding I would personally go for chore (or chore! if it was public API), but only if the new implementation was committed separately. If your commit removes old code and adds new code, it's rather feat or fix (depending what the new code does in relation to the old) or in rare cases refactor (when only deprecating old symbol names and introducing new ones).

I'm looking for feedback by others though, but that's how I would approach the situation.

那你子涵吗名字步步惊心不

Which type can I use to commit a dependency update? I see the build(deps): type often, is it correct?

I use chore: bump deps even though that's probably wrong. build: bump deps makes sense, I'm not sure if the scope of deps that you have in the example build(deps): works though...

If I install tailwindcss and setup the main.css file, then what type should I use? chore(package)?

@mrkhairullah What kind of repository is this? Is it a web application? A documentation site? A monorepo? You need context. It might be refactor(docs): switch to tailwindcss (a repo with a docs/ folder), feat: use tailwindcss (a repo that is just for a website), etc.

@mrkhairullah If you are importing tailwindcss inside main.css for the first time and your application is using this css file, this will most likely impact your app, so I’d go with feat since it is not a fix and I would expect a new version tag for this.

@mrkhairullah What kind of repository is this? Is it a web application? A documentation site? A monorepo? You need context. It might be refactor(docs): switch to tailwindcss (a repo with a docs/ folder), feat: use tailwindcss (a repo that is just for a website), etc.

@uncenter yep web app for personal web use react and vite. When adding tailwind in package.json is a chore? and when adding main.css to commit in git use refactor or feat?

@mrkhairullah If you are importing tailwindcss inside main.css for the first time and your application is using this css file, this will most likely impact your app, so I’d go with feat since it is not a fix and I would expect a new version tag for this.

okey thanks @marijoo

Somthing i use when i do CI is

CI: Add eslint10

useful sir

Really useful.
Thanks

How about change the configuration?

How about change the configuration?

chore prolly

changing project structure, for example creating new src directory, and probably moving some filed into it, is in which type? docs, refactor, chore?

changing project structure, for example creating new src directory, and probably moving some filed into it, is in which type? docs, refactor, chore?

I'd go with refactor.

changing project structure, for example creating new src directory, and probably moving some filed into it, is in which type? docs, refactor, chore?

I'd go with refactor.

Depends. If it‘s a package and the changed project structure eventually impacts users, it could also be a breaking change which should be reflected in a version.

changing project structure, for example creating new src directory, and probably moving some filed into it, is in which type? docs, refactor, chore?

I'd go with refactor.

Depends. If it‘s a package and the changed project structure eventually impacts users, it could also be a breaking change which should be reflected in a version.

No visible change for users is made

Thanks!