ramsey / conventional-commits
A PHP library for creating and validating commit messages according to the Conventional Commits specification. Includes a CaptainHook plugin!
Fund package maintenance!
ramsey
Installs: 4 471
Dependents: 6
Suggesters: 0
Security: 0
Stars: 80
Watchers: 1
Forks: 1
Open Issues: 5
Requires
- php: ^7.4 || ^8
- composer-runtime-api: ^1.1 || ^2
- ext-json: *
- captainhook/captainhook: ^5.3.3
- composer/composer: ^1.1 || ^2.0
- jawira/case-converter: ^3.3
- opis/json-schema: ^1.0.8
- symfony/console: ^5.1.3
- symfony/filesystem: ^5.1
- symfony/polyfill-php80: ^1.15
Requires (Dev)
- ramsey/devtools: ^1.4
- sebastianfeldmann/cli: ^3.3
- sebastianfeldmann/git: ^3.3
- spatie/phpunit-snapshot-assertions: ^4.2
- symfony/process: ^5.1
- dev-main / 1.x-dev
- 1.1.1
- 1.1.0
- 1.0.1
- 1.0.0
- dev-dependabot/composer/composer/composer-2.0.11
- dev-dependabot/composer/symfony/filesystem-5.2.3
- dev-dependabot/composer/symfony/console-5.2.3
- dev-dependabot/composer/composer/composer-2.0.9
- dev-dependabot/composer/spatie/phpunit-snapshot-assertions-4.2.5
- dev-dependabot/composer/captainhook/captainhook-5.4.4
This package is auto-updated.
Last update: 2021-03-02 05:08:55 UTC
README
A PHP library for creating and validating commit messages.
About
ramsey/conventional-commits is a PHP library for creating and validating commit messages according to the Conventional Commits specification. It also includes a CaptainHook plugin!
This project adheres to a code of conduct. By participating in this project and its community, you are expected to uphold this code.
Installation
Install this package as a development dependency using Composer.
composer require --dev ramsey/conventional-commits
Usage
To use the conventional-commits
console command to help you prepare commit
messages according to Conventional Commits, enter the following in your console:
./vendor/bin/conventional-commits prepare
To see all the features of the console command, enter:
./vendor/bin/conventional-commits
Validating Commit Messages
To use the CaptainHook plugin to validate commit messages according to the
Conventional Commits specification, add the following to the commit-msg
property in your captainhook.json
file:
{ "commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\ValidateConventionalCommit" } ] } }
Preparing Commit Messages
You can set up this library to prompt you to prepare commit messages when you
use git commit
!
To use the CaptainHook plugin to prepare commit messages according to the
Conventional Commits specification, add the following to the prepare-commit-msg
property in your captainhook.json
file:
{ "prepare-commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\PrepareConventionalCommit" } ] } }
Configuration
Configuring ramsey/conventional-commits offers control over a few more aspects of commit messages, such as letter case (i.e. lower, upper), allowed types and scopes, required footers, and more.
We look for configuration in one of two places:
composer.json
captainhook.json
⚠️ Please note: if your
composer.json
file is not in the same location as thevendor/
directory, we might have trouble locating it. Feel free to open an issue, and we'll work with you to see if we can find a solution.
Configuration Properties
Configuration for ramsey/conventional-commits consists of the following properties:
Property | Description |
---|---|
typeCase |
The letter case to require for the type. By default, any letter case is acceptable. |
types |
An array of accepted types (in addition to "feat" and "fix"). By default, any type is acceptable. |
scopeCase |
The letter case to require for the scope. By default, any letter case is acceptable. |
scopeRequired |
Whether a scope is required. By default, scope is not required. |
scopes |
An array of accepted scopes. By default, any scope is acceptable. |
descriptionCase |
The letter case to require for the description. By default, any letter case is acceptable. |
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. |
bodyRequired |
Whether a body is required. By default, a body is not required. |
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. |
requiredFooters |
An array of footers that must be provided. By default, footers are not required. |
When specifying configuration, if you wish to use the default behavior for a property, it is not necessary to list the property in your configuration.
Recognized letter cases are:
Identifier | Name | Example |
---|---|---|
ada |
Ada case | The_Quick_Brown_Fox |
camel |
Camel case | theQuickBrownFox |
cobol |
COBOL case | THE-QUICK-BROWN-FOX |
dot |
Dot notation | the.quick.brown.fox |
kebab |
Kebab case | the-quick-brown-fox |
lower |
Lower case | the quick brown fox |
macro |
Macro case | THE_QUICK_BROWN_FOX |
pascal |
Pascal case | TheQuickBrownFox |
sentence |
Sentence case | The quick brown fox |
snake |
Snake case | the_quick_brown_fox |
title |
Title case | The Quick Brown Fox |
train |
Train case | The-Quick-Brown-Fox |
upper |
Upper case | THE QUICK BROWN FOX |
Configuration in composer.json
If you choose to put your configuration in composer.json
, place it within the
extra
property, namespaced under ramsey/conventional-commits
, like this:
{ "extra": { "ramsey/conventional-commits": { "config": { "typeCase": null, "types": [], "scopeCase": null, "scopeRequired": false, "scopes": [], "descriptionCase": null, "descriptionEndMark": null, "bodyRequired": false, "bodyWrapWidth": null, "requiredFooters": [] } } } }
📝 The properties in this example represent the default values.
Configuration in captainhook.json
If you choose to put your configuration in captainhook.json
, you must provide
it for each action you configure, like this:
{ "commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\ValidateConventionalCommit", "options": { "config": { "typeCase": null, "types": [], "scopeCase": null, "scopeRequired": false, "scopes": [], "descriptionCase": null, "descriptionEndMark": null, "bodyRequired": false, "bodyWrapWidth": null, "requiredFooters": [] } } } ] }, "prepare-commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\PrepareConventionalCommit", "options": { "config": { "typeCase": null, "types": [], "scopeCase": null, "scopeRequired": false, "scopes": [], "descriptionCase": null, "descriptionEndMark": null, "bodyRequired": false, "bodyWrapWidth": null, "requiredFooters": [] } } } ] } }
However, if you provide your configuration in composer.json
, it is not
necessary to also provide it in captainhook.json
.
🚨 If using the Git commit hook functionality of Captain Hook, any configuration provided in
captainhook.json
will override configuration incomposer.json
.⚠️ When using the standalone command (i.e.
./vendor/bin/conventional-commits
), only configuration incomposer.json
will apply, unless providing the--config
option.
Configuration in a Separate File
You may also store your configuration in a separate file. For example, you may
store it in conventional-commits.json
, like this:
{ "typeCase": "kebab", "types": [ "ci", "deps", "docs", "refactor", "style", "test" ], "scopeCase": "kebab", "scopeRequired": false, "scopes": [], "descriptionCase": "lower", "descriptionEndMark": "", "bodyRequired": true, "bodyWrapWidth": 72, "requiredFooters": ["Signed-off-by"] }
When stored in a separate file, we won't know where to look for your
configuration, unless you tell us, so you must still provide a small amount of
configuration in either composer.json
or captainhook.json
, so we can find
it.
Here's what this looks like in composer.json
:
{ "extra": { "ramsey/conventional-commits": { "configFile": "./conventional-commits.json" } } }
And here's what this looks like in captainhook.json
:
{ "commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\ValidateConventionalCommit", "options": { "configFile": "./conventional-commits.json" } } ] }, "prepare-commit-msg": { "enabled": true, "actions": [ { "action": "\\Ramsey\\CaptainHook\\PrepareConventionalCommit", "options": { "configFile": "./conventional-commits.json" } } ] } }
Contributing
Contributions are welcome! To contribute, please familiarize yourself with CONTRIBUTING.md.
Copyright and License
The ramsey/conventional-commits library is copyright © Ben Ramsey and licensed for use under the terms of the MIT License (MIT). Please see LICENSE for more information.