README

创建和验证提交信息的 PHP 库。

关于

ramsey/conventional-commits 是一个遵循 Conventional Commits 规范 创建和验证提交信息的 PHP 库。它还包含一个 CaptainHook 行动！

此项目遵守 行为准则。参与此项目和其社区，你应遵守此准则。

安装

使用 Composer 将此包作为开发依赖项安装。

composer require --dev ramsey/conventional-commits

用法

要使用 conventional-commits 控制台命令来帮助你根据 Conventional Commits 准备提交信息，请在你的控制台中输入以下内容

./vendor/bin/conventional-commits prepare

你还可以使用以下命令验证提交信息

./vendor/bin/conventional-commits validate "[commit message]"

如果你在命令行中没有提供提交信息，命令将提示你输入。

要查看控制台命令的所有功能，请输入

./vendor/bin/conventional-commits

CaptainHook 行动

要将 ramsey/conventional-commits 与 CaptainHook 一起作为你的 commit-msg 和/或 prepare-commit-msg Git 钩子的一部分使用，请确保将 CaptainHook 作为开发依赖项要求。

查看 CaptainHook 文档 以获取有关安装和配置 CaptainHook 的更多信息。

验证提交信息

要使用 CaptainHook 行动根据 Conventional Commits 规范验证提交信息，请将以下内容添加到你的 captainhook.json 文件中的 commit-msg 属性

{
    "commit-msg": {
        "enabled": true,
        "actions": [
            {
                "action": "\\Sojeda\\CaptainHook\\ValidateConventionalCommit"
            }
        ]
    }
}

准备提交信息

你可以设置此库，在你使用 git commit 时提示你准备提交信息！

要使用 CaptainHook 行动根据 Conventional Commits 规范准备提交信息，请将以下内容添加到你的 captainhook.json 文件中的 prepare-commit-msg 属性

{
    "prepare-commit-msg": {
        "enabled": true,
        "actions": [
            {
                "action": "\\Sojeda\\CaptainHook\\PrepareConventionalCommit"
            }
        ]
    }
}

配置

配置 ramsey/conventional-commits 提供了对提交信息的一些额外方面的控制，例如字母大小写（例如，小写，大写），允许的类型和作用域，必需的页脚等。

我们在以下两个位置寻找配置

• composer.json
• captainhook.json

⚠️ 请注意：如果你的 composer.json 文件不在与 vendor/ 目录相同的目录中，我们可能难以找到它。请随时提交问题，我们将与你合作，看看是否可以找到解决方案。

配置属性

ramsey/conventional-commits 的配置由以下属性组成

在指定配置时，如果你希望使用属性的默认行为，则不需要在配置中列出该属性。

支持的字母大小写包括

在 composer.json 中的配置

如果你选择在 composer.json 中放置你的配置，请将其放在 extra 属性中，在 ramsey/conventional-commits 命名空间下，如下所示

{
    "extra": {
        "ramsey/conventional-commits": {
            "config": {
                "typeCase": null,
                "types": [],
                "scopeCase": null,
                "scopeRequired": false,
                "scopes": [],
                "descriptionCase": null,
                "descriptionEndMark": null,
                "bodyRequired": false,
                "bodyWrapWidth": null,
                "requiredFooters": []
            }
        }
    }
}

📝 此示例中的属性代表默认值。

在 captainhook.json 中的配置

如果你选择在 captainhook.json 中放置你的配置，你必须为配置的每个 操作 提供它，如下所示

{
    "commit-msg": {
        "enabled": true,
        "actions": [
            {
                "action": "\\Sojeda\\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": "\\Sojeda\\CaptainHook\\PrepareConventionalCommit",
                "options": {
                    "config": {
                        "typeCase": null,
                        "types": [],
                        "scopeCase": null,
                        "scopeRequired": false,
                        "scopes": [],
                        "descriptionCase": null,
                        "descriptionEndMark": null,
                        "bodyRequired": false,
                        "bodyWrapWidth": null,
                        "requiredFooters": []
                    }
                }
            }
        ]
    }
}

但是，如果您在 composer.json 中提供了配置，则不需要在 captainhook.json 中也提供。

🚨 如果使用 Captain Hook 的 Git 提交钩子功能，captainhook.json 中提供的任何配置都将覆盖 composer.json 中的配置。

⚠️ 当使用独立命令（即 ./vendor/bin/conventional-commits）时，除非提供 --config 选项，否则只有 composer.json 中的配置生效。

单独的配置文件

您还可以将配置存储在单独的文件中。例如，您可以将其存储在 conventional-commits.json 中，如下所示

{
    "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"]
}

当存储在单独的文件中时，除非您告诉我们，否则我们不知道在哪里查找您的配置，因此您仍然需要在 composer.json 或 captainhook.json 中提供少量配置，以便我们能够找到它。

以下是它在 composer.json 中的样子

{
    "extra": {
        "ramsey/conventional-commits": {
            "configFile": "./conventional-commits.json"
        }
    }
}

以下是它在 captainhook.json 中的样子

{
    "commit-msg": {
        "enabled": true,
        "actions": [
            {
                "action": "\\Sojeda\\CaptainHook\\ValidateConventionalCommit",
                "options": {
                    "configFile": "./conventional-commits.json"
                }
            }
        ]
    },
    "prepare-commit-msg": {
        "enabled": true,
        "actions": [
            {
                "action": "\\Sojeda\\CaptainHook\\PrepareConventionalCommit",
                "options": {
                    "configFile": "./conventional-commits.json"
                }
            }
        ]
    }
}

贡献

欢迎贡献！要贡献，请熟悉 CONTRIBUTING.md。

协调披露

保护用户信息的安全和保密是我们的首要任务，我们欢迎外部安全研究人员做出贡献。如果您认为您在这个存储库维护的软件中发现了安全问题，请阅读 SECURITY.md 以获取提交漏洞报告的说明。

版权和许可

ramsey/conventional-commits 库的版权 © Ben Ramsey，并按照 MIT 许可协议（MIT）许可使用。有关更多信息，请参阅 LICENSE。