{"id":13395200,"url":"https://github.com/RomuloOliveira/commit-messages-guide","last_synced_at":"2025-03-13T20:31:57.873Z","repository":{"id":39486954,"uuid":"122889876","full_name":"RomuloOliveira/commit-messages-guide","owner":"RomuloOliveira","description":"A guide to understand the importance of commit messages and how to write them well","archived":false,"fork":false,"pushed_at":"2025-02-25T17:58:43.000Z","size":352,"stargazers_count":6747,"open_issues_count":13,"forks_count":341,"subscribers_count":90,"default_branch":"master","last_synced_at":"2025-03-06T00:31:39.458Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RomuloOliveira.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-25T23:59:43.000Z","updated_at":"2025-03-03T15:52:20.000Z","dependencies_parsed_at":"2024-12-31T17:33:21.808Z","dependency_job_id":null,"html_url":"https://github.com/RomuloOliveira/commit-messages-guide","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomuloOliveira%2Fcommit-messages-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomuloOliveira%2Fcommit-messages-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomuloOliveira%2Fcommit-messages-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomuloOliveira%2Fcommit-messages-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RomuloOliveira","download_url":"https://codeload.github.com/RomuloOliveira/commit-messages-guide/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243478335,"owners_count":20297237,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T17:01:45.996Z","updated_at":"2025-03-13T20:31:57.861Z","avatar_url":"https://github.com/RomuloOliveira.png","language":null,"funding_links":[],"categories":["Others","GitHub","Other","Management / dealing with people","🔧 Git","Git Documentation Guides"],"sub_categories":["Git","git help","☸️ Kubernetes","Commit Message Guides"],"readme":"# Commit messages guide\n\n[![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/RomuloOliveira)\n\nA guide to understanding the importance of commit messages and how to write them well.\n\nIt may help you to learn what a commit is, why it is important to write good messages, best practices and some tips to plan and (re)write a good commit history.\n\n## Available languages\n\n- [English](README.md)\n- [Português](README_pt-BR.md)\n- [Deutsch](README_de-DE.md)\n- [Español](README_es-AR.md)\n- [Italiano](README_it-IT.md)\n- [한국어](README_ko-KR.md)\n- [Русский](README_ru-RU.md)\n- [简体中文](README_zh-CN.md)\n- [日本語](README_ja-JP.md)\n- [Українська](README_ua-UA.md)\n- [Türkçe](README_tr-TR.md)\n- [ngôn ngữ tiếng Việt](README_vi-VN.md)\n- [繁體中文](README_zh-TW.md)\n- [ελληνικά](README_gr-GR.md)\n- [Française](README_fr-FR.md)\n- [پارسی](README_fa-IR.md)\n- [Polish](README_pl-PL.md)\n- [Azərbaycanca](README_az-AZ.md)\n\n## What is a \"commit\"?\n\nIn simple terms, a commit is a _snapshot_ of your local files, written in your local repository.\nContrary to what some people think, [git doesn't store only the difference between the files, it stores a full version of all files](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_snapshots_not_differences).\nFor files that didn't change from one commit to another, git stores just a link to the previous identical file that is already stored.\n\nThe image below shows how git stores data over time, in which each \"Version\" is a commit:\n\n![](https://i.stack.imgur.com/AQ5TG.png)\n\n## Why are commit messages important?\n\n- To speed up and streamline code reviews\n- To help in the understanding of a change\n- To explain \"the whys\" that cannot be described only with code\n- To help future maintainers figure out why and how changes were made, making troubleshooting and debugging easier\n\nTo maximize those outcomes, we can use some good practices and standards described in the next section.\n\n## Good practices\n\nThese are some practices collected from my experiences, internet articles, and other guides. If you have others (or disagree with some) feel free to open a Pull Request and contribute.\n\n### Use imperative form\n\n```\n# Good\nUse InventoryBackendPool to retrieve inventory backend\n```\n\n```\n# Bad\nUsed InventoryBackendPool to retrieve inventory backend\n```\n\n_But why use the imperative form?_\n\nA commit message describes what the referenced change actually **does**, its effects, not what was done.\n\n\n### Capitalize the first letter\n\n```\n# Good\nAdd `use` method to Credit model\n```\n\n```\n# Bad\nadd `use` method to Credit model\n```\n\nThe reason that the first letter should be capitalized is to follow the grammar rule of using capital letters at the beginning of sentences.\n\nThe use of this practice may vary from person to person, team to team, or even from language to language.\nCapitalized or not, an important point is to stick to a single standard and follow it.\n\n### Try to communicate what the change does without having to look at the source code\n\n```\n# Good\nAdd `use` method to Credit model\n\n```\n\n```\n# Bad\nAdd `use` method\n```\n\n```\n# Good\nIncrease left padding between textbox and layout frame\n```\n\n```\n# Bad\nAdjust css\n```\n\nIt is useful in many scenarios (e.g. multiple commits, several changes and refactors) to help reviewers understand what the committer was thinking.\n\n### Use the message body to explain \"why\", \"for what\", \"how\" and additional details\n\nFocus on the \"why\" instead of \"what\" (although \"what\" and \"how\" are still important).\nIf, for example, your commit message is a restatement of the diff, it may be important to\nrethink it.\n\n```\n# Good\nFix method name of InventoryBackend child classes\n\nClasses derived from InventoryBackend were not\nrespecting the base class interface.\n\nIt worked because the cart was calling the backend implementation\nincorrectly.\n```\n\n```\n# Good\nSerialize and deserialize credits to json in Cart\n\nConvert the Credit instances to dict for two main reasons:\n\n  - Pickle relies on file path for classes and we do not want to break up\n    everything if a refactor is needed\n  - Dict and built-in types are pickleable by default\n```\n\n```\n# Good\nAdd `use` method to Credit\n\nChange from namedtuple to class because we need to\nsetup a new attribute (in_use_amount) with a new value\n```\n\nThe subject and the body of the messages are separated by a blank line.\nAdditional blank lines are considered as a part of the message body.\n\nCharacters like `-`, `*` and \\` are elements that improve readability.\n\n### Avoid generic messages or messages without any context\n\n```\n# Bad\nFix this\n\nFix stuff\n\nIt should work now\n\nChange stuff\n\nAdjust css\n```\n\n### Avoid language such as \"this PR\", \"this commit\", \"this patch\"\n\nYou don't have to refer to the commit by itself. We **know** that this is a patch, commit or PR.\n\n```\n# Bad\nThis commit does x and y...\n\nThis PR does x and y...\n\nThis Patch x and y...\n\n# Good\n\nX and y are done...\n```\n\n### Avoid personal language (e.g. pronouns)\n\nA thing that can be learned from academic writing and brought to commit messages is to avoid using personal\nlanguage.\n\n```\n# Bad\nI fixed the problem.\n\n# Good\nThe problem has been fixed by doing x and y...\n```\n\n### Limit the number of characters\n\n[It's recommended](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) to use a maximum of 50 characters for the subject and 72 for the body.\n\n### Keep language consistency\n\nFor project owners: Choose a language and write all commit messages using that language. Ideally, it should match the code comments, default translation locale (for localized projects), etc.\n\nFor contributors: Write your commit messages using the same language as the existing commit history.\n\n```\n# Good\nababab Add `use` method to Credit model\nefefef Use InventoryBackendPool to retrieve inventory backend\nbebebe Fix method name of InventoryBackend child classes\n```\n\n```\n# Good (Portuguese example)\nababab Adiciona o método `use` ao model Credit\nefefef Usa o InventoryBackendPool para recuperar o backend de estoque\nbebebe Corrige nome de método na classe InventoryBackend\n```\n\n```\n# Bad (mixes English and Portuguese)\nababab Usa o InventoryBackendPool para recuperar o backend de estoque\nefefef Add `use` method to Credit model\ncdcdcd Agora vai\n```\n\n### Template\n\nThis is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).\n\n```\nSummarize changes in around 50 characters or less\n\nMore detailed explanatory text, if necessary. Wrap it to about 72\ncharacters or so. In some contexts, the first line is treated as the\nsubject of the commit and the rest of the text as the body. The\nblank line separating the summary from the body is critical (unless\nyou omit the body entirely); various tools like `log`, `shortlog`\nand `rebase` can get confused if you run the two together.\n\nExplain the problem that this commit is solving. Focus on why you\nare making this change as opposed to how (the code explains that).\nAre there side effects or other unintuitive consequences of this\nchange? Here's the place to explain them.\n\nFurther paragraphs come after blank lines.\n\n - Bullet points are okay, too\n\n - Typically a hyphen or asterisk is used for the bullet, preceded\n   by a single space, with blank lines in between, but conventions\n   vary here\n\nIf you use an issue tracker, put references to them at the bottom,\nlike this:\n\nResolves: #123\nSee also: #456, #789\n```\n\n## Notes on PR messages and cover letters\n\nMost developers open Pull Requests (PR) on a Git repo through a platform (Github, Gitlab),\nwhile kernel developers  and people who send patches through email ([yes, that's a\nthing](https://git-scm.com/docs/git-send-email/2.45.0) refer to it as \"cover letter\".\n\nA good cover letter, or PR message, will summarize, give background and context to a series of\ncommits that are related. Good writing on this part will help to \"sell\" your commit series to\nthe maintainers of a project, as they'll be able to understand why you are presenting such changes\ntogether.\n\nIf you're writing a smaller (single or a few commits) change, treat the first commit as a cover letter.\nGithub, for example, uses this first commit as the default PR message.\n\nHere's an [example](https://lore.kernel.org/lkml/20230414225551.858160935@linutronix.de/) of a good cover\nletter sent on the Linux kernel mailing list. It contains:\n\n- A description of the overall changes and why they were made;\n\n- Background, or any important information that is needed to understand these changes;\n\n- A breakdown of the solution and the approach taken to reach such solution;\n\n- Caveats, or things that could go wrong and must be considered before applying such changes;\n\n- Possible enhancements, a section describing opportunities for future changes that are out of the scope\n  for the current commit set;\n\n## Signing off your commits and following guidelines\n\nOpen source projects often require you to sign your code and follow some guidelines. One such example is\nthe Developer Certificate of Origin (DCO)[https://developercertificate.org/], which you have to abide to\nwhen contributing to projects by The Linux Foundation, the Cloud Native Computing Foundation and many\nothers.\n\nThis means that you have to use your **real name** (i.e. a name that identifies you, _not necessarily your\nlegal name_) and to sign off your commits. Avoid pseudonyms or false names. Further reading about real names\n[here](https://www.mail-archive.com/kernelnewbies@kernelnewbies.org/msg22178.html).\n\nUse `git config` to set your name and email.\n\n``` sh\n# You can apply these changes locally, to a single repo\ngit config --local user.name \"Jane Doe\"\ngit config --local user.email \"janedoe@janedoe.com\"\n\n# Or globally\ngit config --global user.name \"Jane Doe\"\ngit config --global user.email \"janedoe@janedoe.com\"\n```\n\nWhen doing a commit, add the `-s` flag to `git commit` and that will add a `Signed-off-by: ` line to your\ncommit.\n\nAside from adding this line to the commit, it's also important to use GPG for signing your commits.\n\nGPG, or GNU Privacy Guard, is a tool that allows you to encrypt and tamperproof documents. You can use it,\nfor example, to sign emails and ensure that they haven't been modified without your consent. In the git\nworld, this is how you tell that a commit has been made by you and has not been tampered before reaching\nother people.\n\nGithub has more [information](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account)\nabout how to generate and add a GPG key to your account. [This documentation](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key)\nteaches how to use gpgsign for commits.\n\nMore information about working with GPG [here](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work).\n\nFor even more security, you can setup [pinentry](https://www.gnupg.org/related_software/pinentry/index.html)\nto add physical layers of security to GPG, such as signing your commits with Yubikey of Touch ID.\n\n## Rebase vs. Merge\n\nThis section is a **TL;DR** of Atlassian's excellent tutorial, [\"Merging vs. Rebasing\"](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).\n\n![](https://wac-cdn.atlassian.com/dam/jcr:01b0b04e-64f3-4659-af21-c4d86bc7cb0b/01.svg?cdnVersion=hq)\n\n### Rebase\n\n**TL;DR:** Applies your branch commits, one by one, upon the base branch, generating a new tree.\n\n![](https://wac-cdn.atlassian.com/dam/jcr:5b153a22-38be-40d0-aec8-5f2fffc771e5/03.svg?cdnVersion=hq)\n\n### Merge\n\n**TL;DR:** Creates a new commit, called (appropriately) a _merge commit_, with the differences between the two branches.\n\n![](https://wac-cdn.atlassian.com/dam/jcr:e229fef6-2c2f-4a4f-b270-e1e1baa94055/02.svg?cdnVersion=hq)\n\n### Why do some people prefer to rebase over merge?\n\nI particularly prefer to rebase over merge. The reasons include:\n\n- It generates a \"clean\" history, without unnecessary merge commits\n- _What you see is what you get_, i.e., in a code review all changes come from a specific and entitled commit, avoiding changes hidden in merge commits\n- More merges are resolved by the committer, and every merge change is in a commit with a proper message\n  - It's unusual to dig in and review merge commits, so avoiding them ensures all changes have a commit where they belong\n\n### When to squash\n\n\"Squashing\" is the process of taking a series of commits and condensing them into a single commit.\n\nIt's useful in several situations, e.g.:\n\n- Reducing commits with little or no context (typo corrections, formatting, forgotten stuff)\n- Joining separate changes that make more sense when applied together\n- Rewriting _work in progress_ commits\n\n### When to avoid rebase or squash?\n\nAvoid rebase and squash in public commits or in shared branches where multiple people work on.\nRebase and squash rewrite history and overwrite existing commits, doing it on commits that are on shared branches (i.e., commits pushed to a remote repository or that comes from others branches) can cause confusion and people may lose their changes (both locally and remotely) because of divergent trees and conflicts.\n\n## Useful git commands\n\n### rebase -i\n\nUse it to squash commits, edit messages, rewrite/delete/reorder commits, etc.\n\n```\npick 002a7cc Improve description and update document title\npick 897f66d Add contributing section\npick e9549cf Add a section of Available languages\npick ec003aa Add \"What is a commit\" section\"\npick bbe5361 Add source referencing as a point of help wanted\npick b71115e Add a section explaining the importance of commit messages\npick 669bf2b Add \"Good practices\" section\npick d8340d7 Add capitalization of first letter practice\npick 925f42b Add a practice to encourage good descriptions\npick be05171 Add a section showing good uses of message body\npick d115bb8 Add generic messages and column limit sections\npick 1693840 Add a section about language consistency\npick 80c5f47 Add commit message template\npick 8827962 Fix triple \"m\" typo\npick 9b81c72 Add \"Rebase vs Merge\" section\n\n# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)\n#\n# Commands:\n# p, pick = use commit\n# r, reword = use commit, but edit the commit message\n# e, edit = use commit, but stop for amending\n# s, squash = use commit, but meld into the previous commit\n# f, fixup = like \"squash\", but discard this commit's log message\n# x, exec = run command (the rest of the line) using shell\n# d, drop = remove commit\n#\n# These lines can be re-ordered; they are executed from top to bottom.\n#\n# If you remove a line here THAT COMMIT WILL BE LOST.\n#\n# However, if you remove everything, the rebase will be aborted.\n#\n# Note that empty commits are commented out\n```\n\n#### fixup\n\nUse it to clean up commits easily and without needing a more complex rebase.\n[This article](http://fle.github.io/git-tip-keep-your-branch-clean-with-fixup-and-autosquash.html) has very good examples of how and when to do it.\n\n### cherry-pick\n\nIt is very useful to apply that commit you made on the wrong branch, without the need to code it again.\n\nExample:\n\n```\n$ git cherry-pick 790ab21\n[master 094d820] Fix English grammar in Contributing\n Date: Sun Feb 25 23:14:23 2018 -0300\n 1 file changed, 1 insertion(+), 1 deletion(-)\n```\n\n### add/checkout/reset [--patch | -p]\n\nLet's say we have the following diff:\n\n```diff\ndiff --git a/README.md b/README.md\nindex 7b45277..6b1993c 100644\n--- a/README.md\n+++ b/README.md\n@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend\n ``\n # Bad (mixes English and Portuguese)\n ababab Usa o InventoryBackendPool para recuperar o backend de estoque\n-efefef Add `use` method to Credit model\n cdcdcd Agora vai\n ``\n\n+### Template\n+\n+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).\n+\n ## Contributing\n\n Any kind of help would be appreciated. Example of topics that you can help me with:\n@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi\n\n - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)\n - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)\n+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)\n```\n\nWe can use `git add -p` to add only the patches we want to, without the need to change the code that is already written.\nIt's useful to split a big change into smaller commits or to reset/checkout specific changes.\n\n```\nStage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s\nSplit into 2 hunks.\n```\n\n#### hunk 1\n\n```diff\n@@ -186,7 +186,6 @@\n ``\n # Bad (mixes English and Portuguese)\n ababab Usa o InventoryBackendPool para recuperar o backend de estoque\n-efefef Add `use` method to Credit model\n cdcdcd Agora vai\n ``\n\nStage this hunk [y,n,q,a,d,/,j,J,g,e,?]?\n```\n\n#### hunk 2\n\n```diff\n@@ -190,6 +189,10 @@\n ``\n cdcdcd Agora vai\n ``\n\n+### Template\n+\n+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).\n+\n ## Contributing\n\n Any kind of help would be appreciated. Example of topics that you can help me with:\nStage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?\n\n```\n\n#### hunk 3\n\n```diff\n@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi\n\n - [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)\n - [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)\n+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)\n```\n\n## Other interesting stuff\n\n- https://whatthecommit.com/\n- https://gitmoji.carloscuesta.me/\n\n## Like it?\n\n[Say thanks!](https://saythanks.io/to/RomuloOliveira)\n\n## Contributing\n\nAny kind of help would be appreciated. Example of topics that you can help me with:\n\n- Grammar and spelling corrections\n- Translation to other languages\n- Improvement of source referencing\n- Incorrect or incomplete information\n\n## Inspirations, sources and further reading\n\n- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)\n- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)\n- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)\n- [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)\n- [Pro Git Book - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)\n- [Philosophy of Linux kernel patches](https://kernelnewbies.org/PatchPhilosophy)\n- [The perfect patch](https://www.ozlabs.org/~akpm/stuff/tpp.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRomuloOliveira%2Fcommit-messages-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRomuloOliveira%2Fcommit-messages-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRomuloOliveira%2Fcommit-messages-guide/lists"}