{"id":20004739,"url":"https://github.com/ramsey/conventional-commits","last_synced_at":"2025-05-15T07:06:08.366Z","repository":{"id":38332924,"uuid":"278958817","full_name":"ramsey/conventional-commits","owner":"ramsey","description":":yo_yo: A PHP library for creating and validating commit messages according to the Conventional Commits specification. Includes a CaptainHook plugin!","archived":false,"fork":false,"pushed_at":"2025-03-24T21:39:48.000Z","size":403,"stargazers_count":188,"open_issues_count":12,"forks_count":22,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-10T06:24:37.584Z","etag":null,"topics":["captainhook","commit","commit-msg","conventional","conventional-commits","git","hook","php","plugin"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ramsey.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ramsey"}},"created_at":"2020-07-11T23:37:06.000Z","updated_at":"2025-03-09T11:02:44.000Z","dependencies_parsed_at":"2024-06-18T12:30:17.689Z","dependency_job_id":"c95a0d0d-23ce-43ea-8e3d-eca851c21599","html_url":"https://github.com/ramsey/conventional-commits","commit_stats":{"total_commits":127,"total_committers":5,"mean_commits":25.4,"dds":"0.22834645669291342","last_synced_commit":"7c8a4fd4d34dfbcab61685dd93b9a09752354f22"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Fconventional-commits","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Fconventional-commits/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Fconventional-commits/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Fconventional-commits/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramsey","download_url":"https://codeload.github.com/ramsey/conventional-commits/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254292042,"owners_count":22046426,"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":["captainhook","commit","commit-msg","conventional","conventional-commits","git","hook","php","plugin"],"created_at":"2024-11-13T05:32:43.520Z","updated_at":"2025-05-15T07:06:03.356Z","avatar_url":"https://github.com/ramsey.png","language":"PHP","funding_links":["https://github.com/sponsors/ramsey"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eramsey/conventional-commits\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cstrong\u003eA PHP library for creating and validating commit messages.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/ramsey/conventional-commits\"\u003e\u003cimg src=\"http://img.shields.io/badge/source-ramsey/conventional--commits-blue.svg?style=flat-square\" alt=\"Source Code\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://packagist.org/packages/ramsey/conventional-commits\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/ramsey/conventional-commits.svg?style=flat-square\u0026label=release\" alt=\"Download Package\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://php.net\"\u003e\u003cimg src=\"https://img.shields.io/packagist/php-v/ramsey/conventional-commits.svg?style=flat-square\u0026colorB=%238892BF\" alt=\"PHP Programming Language\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/ramsey/conventional-commits/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/packagist/l/ramsey/conventional-commits.svg?style=flat-square\u0026colorB=darkcyan\" alt=\"Read License\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/ramsey/conventional-commits/actions/workflows/continuous-integration.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/ramsey/conventional-commits/continuous-integration.yml?branch=main\u0026style=flat-square\u0026logo=github\" alt=\"Build Status\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://codecov.io/gh/ramsey/conventional-commits\"\u003e\u003cimg src=\"https://img.shields.io/codecov/c/gh/ramsey/conventional-commits?label=codecov\u0026logo=codecov\u0026style=flat-square\" alt=\"Codecov Code Coverage\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## About\n\nramsey/conventional-commits is a PHP library for creating and validating commit\nmessages according to the [Conventional Commits specification][]. It also\nincludes a [CaptainHook][] action!\n\nThis project adheres to a [code of conduct](CODE_OF_CONDUCT.md).\nBy participating in this project and its community, you are expected to\nuphold this code.\n\n## Installation\n\nInstall this package as a development dependency using\n[Composer](https://getcomposer.org).\n\n``` bash\ncomposer require --dev ramsey/conventional-commits\n```\n\n## Usage\n\nTo use the `conventional-commits` console command to help you prepare commit\nmessages according to Conventional Commits, enter the following in your console:\n\n``` bash\n./vendor/bin/conventional-commits prepare\n```\n\nYou can also validate the commit message using the following command:\n\n``` bash\n./vendor/bin/conventional-commits validate \"[commit message]\"\n```\n\nIf you don't provide a commit message in the command line, the command will\nprompt you for it.\n\nTo see all the features of the console command, enter:\n\n``` bash\n./vendor/bin/conventional-commits\n```\n\n### CaptainHook Action\n\nTo use ramsey/conventional-commits with CaptainHook as part of your `commit-msg`\nand/or `prepare-commit-msg` Git hooks, be sure to require CaptainHook as a\ndevelopment dependency.\n\nCheck out the [CaptainHook documentation](https://github.com/captainhookphp/captainhook)\nfor more information on installing and configuring CaptainHook.\n\n#### Validating Commit Messages\n\nTo use the CaptainHook action to validate commit messages according to the\nConventional Commits specification, add the following to the `commit-msg`\nproperty in your `captainhook.json` file:\n\n``` json\n{\n    \"commit-msg\": {\n        \"enabled\": true,\n        \"actions\": [\n            {\n                \"action\": \"\\\\Ramsey\\\\CaptainHook\\\\ValidateConventionalCommit\"\n            }\n        ]\n    }\n}\n```\n\n#### Preparing Commit Messages\n\nYou can set up this library to prompt you to prepare commit messages when you\nuse `git commit`!\n\nTo use the CaptainHook action to prepare commit messages according to the\nConventional Commits specification, add the following to the `prepare-commit-msg`\nproperty in your `captainhook.json` file:\n\n``` json\n{\n    \"prepare-commit-msg\": {\n        \"enabled\": true,\n        \"actions\": [\n            {\n                \"action\": \"\\\\Ramsey\\\\CaptainHook\\\\PrepareConventionalCommit\"\n            }\n        ]\n    }\n}\n```\n\n### Configuration\n\nConfiguring ramsey/conventional-commits offers control over a few more aspects\nof commit messages, such as letter case (i.e. lower, upper), allowed types and\nscopes, required footers, and more.\n\nWe look for configuration in one of two places:\n\n* `composer.json`\n* `captainhook.json`\n\n\u003e ⚠️ **Please note:** if your `composer.json` file is not in the same location as\n\u003e the `vendor/` directory, we might have trouble locating it. Feel free to open\n\u003e an issue, and we'll work with you to see if we can find a solution.\n\n#### Configuration Properties\n\nConfiguration for ramsey/conventional-commits consists of the following\nproperties:\n\n| Property             | Description                                                                                                                                                                                       |\n|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `typeCase`           | The letter case to require for the type. By default, any letter case is acceptable.                                                                                                               |\n| `types`              | An array of accepted types (in addition to \"feat\" and \"fix\"). By default, any type is acceptable.                                                                                                 |\n| `scopeCase`          | The letter case to require for the scope. By default, any letter case is acceptable.                                                                                                              |\n| `scopeRequired`      | Whether a scope is required. By default, scope is not required.                                                                                                                                   |\n| `scopes`             | An array of accepted scopes. By default, any scope is acceptable.                                                                                                                                 |\n| `descriptionCase`    | The letter case to require for the description. By default, any letter case is acceptable.                                                                                                        |\n| `descriptionEndMark` | A character to require at the end of the description. By default, any character is allowed. Use an empty string to indicate a punctuation character is not allowed at the end of the description. |\n| `bodyRequired`       | Whether a body is required. By default, a body is not required.                                                                                                                                   |\n| `bodyWrapWidth`      | An integer indicating the character width to auto-wrap the body of the commit message. By default, the commit body does not auto-wrap.                                                            |\n| `requiredFooters`    | An array of footers that must be provided. By default, footers are not required.                                                                                                                  |\n\nWhen specifying configuration, if you wish to use the default behavior for a\nproperty, it is not necessary to list the property in your configuration.\n\nRecognized letter cases are:\n\n| Identifier | Name          | Example               |\n|------------|---------------|-----------------------|\n| `ada`      | Ada case      | `The_Quick_Brown_Fox` |\n| `camel`    | Camel case    | `theQuickBrownFox`    |\n| `cobol`    | COBOL case    | `THE-QUICK-BROWN-FOX` |\n| `dot`      | Dot notation  | `the.quick.brown.fox` |\n| `kebab`    | Kebab case    | `the-quick-brown-fox` |\n| `lower`    | Lower case    | `the quick brown fox` |\n| `macro`    | Macro case    | `THE_QUICK_BROWN_FOX` |\n| `pascal`   | Pascal case   | `TheQuickBrownFox`    |\n| `sentence` | Sentence case | `The quick brown fox` |\n| `snake`    | Snake case    | `the_quick_brown_fox` |\n| `title`    | Title case    | `The Quick Brown Fox` |\n| `train`    | Train case    | `The-Quick-Brown-Fox` |\n| `upper`    | Upper case    | `THE QUICK BROWN FOX` |\n\n#### Configuration in composer.json\n\nIf you choose to put your configuration in `composer.json`, place it within the\n`extra` property, namespaced under `ramsey/conventional-commits`, like this:\n\n``` json\n{\n    \"extra\": {\n        \"ramsey/conventional-commits\": {\n            \"config\": {\n                \"typeCase\": null,\n                \"types\": [],\n                \"scopeCase\": null,\n                \"scopeRequired\": false,\n                \"scopes\": [],\n                \"descriptionCase\": null,\n                \"descriptionEndMark\": null,\n                \"bodyRequired\": false,\n                \"bodyWrapWidth\": null,\n                \"requiredFooters\": []\n            }\n        }\n    }\n}\n```\n\n\u003e 📝 The properties in this example represent the default values.\n\n#### Configuration in captainhook.json\n\nIf you choose to put your configuration in `captainhook.json`, you must provide\nit for *each action* you configure, like this:\n\n``` json\n{\n    \"commit-msg\": {\n        \"enabled\": true,\n        \"actions\": [\n            {\n                \"action\": \"\\\\Ramsey\\\\CaptainHook\\\\ValidateConventionalCommit\",\n                \"options\": {\n                    \"config\": {\n                        \"typeCase\": null,\n                        \"types\": [],\n                        \"scopeCase\": null,\n                        \"scopeRequired\": false,\n                        \"scopes\": [],\n                        \"descriptionCase\": null,\n                        \"descriptionEndMark\": null,\n                        \"bodyRequired\": false,\n                        \"bodyWrapWidth\": null,\n                        \"requiredFooters\": []\n                    }\n                }\n            }\n        ]\n    },\n    \"prepare-commit-msg\": {\n        \"enabled\": true,\n        \"actions\": [\n            {\n                \"action\": \"\\\\Ramsey\\\\CaptainHook\\\\PrepareConventionalCommit\",\n                \"options\": {\n                    \"config\": {\n                        \"typeCase\": null,\n                        \"types\": [],\n                        \"scopeCase\": null,\n                        \"scopeRequired\": false,\n                        \"scopes\": [],\n                        \"descriptionCase\": null,\n                        \"descriptionEndMark\": null,\n                        \"bodyRequired\": false,\n                        \"bodyWrapWidth\": null,\n                        \"requiredFooters\": []\n                    }\n                }\n            }\n        ]\n    }\n}\n```\n\nHowever, if you provide your configuration in `composer.json`, it is not\nnecessary to also provide it in `captainhook.json`.\n\n\u003e 🚨 If using the Git commit hook functionality of Captain Hook, any\n\u003e configuration provided in `captainhook.json` will override configuration\n\u003e in `composer.json`.\n\u003e\n\u003e ⚠️ When using the standalone command (i.e. `./vendor/bin/conventional-commits`),\n\u003e only configuration in `composer.json` will apply, unless providing the\n\u003e `--config` option.\n\n#### Configuration in a Separate File\n\nYou may also store your configuration in a separate file. For example, you may\nstore it in `conventional-commits.json`, like this:\n\n``` json\n{\n    \"typeCase\": \"kebab\",\n    \"types\": [\n        \"ci\",\n        \"deps\",\n        \"docs\",\n        \"refactor\",\n        \"style\",\n        \"test\"\n    ],\n    \"scopeCase\": \"kebab\",\n    \"scopeRequired\": false,\n    \"scopes\": [],\n    \"descriptionCase\": \"lower\",\n    \"descriptionEndMark\": \"\",\n    \"bodyRequired\": true,\n    \"bodyWrapWidth\": 72,\n    \"requiredFooters\": [\"Signed-off-by\"]\n}\n```\n\nWhen stored in a separate file, we won't know where to look for your\nconfiguration, unless you tell us, so you must still provide a small amount of\nconfiguration in either `composer.json` or `captainhook.json`, so we can find\nit.\n\nHere's what this looks like in `composer.json`:\n\n``` json\n{\n    \"extra\": {\n        \"ramsey/conventional-commits\": {\n            \"configFile\": \"./conventional-commits.json\"\n        }\n    }\n}\n```\n\nAnd here's what this looks like in `captainhook.json`:\n\n``` json\n{\n    \"commit-msg\": {\n        \"enabled\": true,\n        \"actions\": [\n            {\n                \"action\": \"\\\\Ramsey\\\\CaptainHook\\\\ValidateConventionalCommit\",\n                \"options\": {\n                    \"configFile\": \"./conventional-commits.json\"\n                }\n            }\n        ]\n    },\n    \"prepare-commit-msg\": {\n        \"enabled\": true,\n        \"actions\": [\n            {\n                \"action\": \"\\\\Ramsey\\\\CaptainHook\\\\PrepareConventionalCommit\",\n                \"options\": {\n                    \"configFile\": \"./conventional-commits.json\"\n                }\n            }\n        ]\n    }\n}\n```\n\n## Contributing\n\nContributions are welcome! To contribute, please familiarize yourself with\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Coordinated Disclosure\n\nKeeping user information safe and secure is a top priority, and we welcome the\ncontribution of external security researchers. If you believe you've found a\nsecurity issue in software that is maintained in this repository, please read\n[SECURITY.md](SECURITY.md) for instructions on submitting a vulnerability report.\n\n## Copyright and License\n\nThe ramsey/conventional-commits library is copyright © [Ben Ramsey](https://benramsey.com)\nand licensed for use under the terms of the MIT License (MIT). Please see\n[LICENSE](LICENSE) for more information.\n\n\n[Conventional Commits specification]: https://www.conventionalcommits.org/en/v1.0.0/\n[CaptainHook]: https://github.com/captainhookphp/captainhook\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framsey%2Fconventional-commits","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framsey%2Fconventional-commits","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framsey%2Fconventional-commits/lists"}