传统的

常规是用于解析和处理结构化提交的可扩展命令行工具。它支持常规提交标准，但可以扩展以支持任何其他提交格式。

有关此工具支持的功能类型的示例，请参见CHANGELOG.md 。

要求

• Python 3.8+
• Git 2.27.0

安装

使用pip安装和更新：

$ pip install -U conventional

用法

列出提交

$ conventional list-commits

该list-commits命令将从存储库中检索 git 提交并以 json 格式输出它们，每行每个提交一个对象，然后可以通过管道传输到例如jq. 默认情况下，该命令将输出从提交中检索到的原始字段，包括提交的主题、正文、作者和日期。

--parse该命令可以通过提供标志来自动解析提交。如果指定了标志，则将以Parsing Commits中描述的格式输出提交。此命令将支持该--include-unparsed标志，如果提供了未能解析的提交，则将输出缺少该data字段。

解析提交

$ conventional [--config .conventional.yaml] parse-commit

该parse-commit命令将从文件或标准输入读取提交，并尝试使用配置的解析器解析它们。此命令将以 json 格式输出提交，每行一个对象，格式为{"source": {}, "data": {}}，其中source包含原始提交字段并data包含从提交中解析的字段。

如果无法解析提交，则默认情况下它不会包含在输出中。可以使用该--include-unparsed标志禁用此行为，在这种情况下，无法解析的提交将输出缺少该data字段（因为无法解析任何字段）。

请参阅下面的解析器以获取包含在conventional.

将提交呈现到模板中

$ conventional [--config .conventional.yaml] template

该template命令将读取提交流，通过查看提交上的标签确定不同的“版本”，并使用配置的模板呈现它们。模板使用 Jinja2 呈现，并提供版本列表以及配置文件中指定的任何自定义配置。

请参阅下面的模板以获取conventional.

笔记

在内部，一些命令将使用其他命令来提供附加功能并简化常见用例。

例如...

$ conventional list-commits --parse # is equivalent to
$ conventional list-commits | conventional parse-commit

和...

$ conventional template # is equivalent to
$ conventional list-commits | conventional parse-commit | conventional template --input -

这意味着，例如，如果您希望使用conventional template但仅使用自最后一个标签创建的提交，您可以使用 command conventional list-commits --from-last-tag | conventional template --input -。

配置

--config-file除了命令行参数外，还可以在调用时通过参数提供配置文件conventional。默认情况下conventional，配置为解析符合常规提交标准的提交并将它们呈现到更改日志中，但这可以通过配置配置文件中的parser和template部分以及其他内容来更改。

查看config_default.yaml以查看配置文件中可以包含的内容。

下面是默认提供的解析器和模板列表conventional。

解析器

模块：conventional.parser，名称：ConventionalCommitParser

解析符合常规提交标准的提交。

支持的配置：

• typestype- 允许在提交消息中用作 a 的值。使用此列表中未指定类型的任何提交都将无法正确解析。

模板

包：常规，名称：changelog.md

以适合存储在 CHANGELOG.md 文件中的格式呈现提交。

支持的配置：

• commit-link-pattern- 此模式将用于生成提交的链接，{rev}替换为提交的哈希并{short_rev}替换为提交的短哈希。例如，如果您使用的是 Github，这可能是https://github.com/[owner]/[repo]/commit/{rev}.
• compare-link-pattern- 此模式将用于生成当前版本与先前版本之间比较的链接，{to}替换为当前版本{from}的标签并替换为先前版本的标签。例如，在 Github 中，这可能是https://github.com/[owner]/[repo]/compare/{from}...{to}
• issue-link-pattern- 此模式将用于生成指向提交中任何问题引用的链接，{issue}并扩展为问题的 ID。例如，如果您使用 Jira，则此格式可能是https://[company].atlassian.net/browse/{issue}.
• version-link-pattern- 此模式将用于为给定版本生成指向源的链接，{tag}并由给定版本的标签替换。例如，在 Github 中，这可能是https://github.com/[owner]/[repo]/tree/{tag}
• type-headings- 提交“类型”到应在标题中用于特定类型更改的文本的映射。默认为{"feat": "Feature", "fix": "Fixes"}.

包：常规，名称：slack.md

以适合发布到 Slack 的格式呈现提交。

支持的配置：

• commit-link-pattern- 此模式将用于生成提交的链接，{rev}替换为提交的哈希并{short_rev}替换为提交的短哈希。例如，如果您使用的是 Github，这可能是https://github.com/[owner]/[repo]/commit/{rev}.
• compare-link-pattern- 此模式将用于生成当前版本与先前版本之间比较的链接，{to}替换为当前版本{from}的标签并替换为先前版本的标签。例如，在 Github 中，这可能是https://github.com/[owner]/[repo]/compare/{from}...{to}
• issue-link-pattern- 此模式将用于生成指向提交中任何问题引用的链接，{issue}并扩展为问题的 ID。例如，如果您使用 Jira，则此格式可能是https://[company].atlassian.net/browse/{issue}.
• version-link-pattern- 此模式将用于为给定版本生成指向源的链接，{tag}并由给定版本的标签替换。例如，在 Github 中，这可能是https://github.com/[owner]/[repo]/tree/{tag}
• type-headings- 提交“类型”到应在标题中用于特定类型更改的文本的映射。默认为{"feat": "Feature", "fix": "Fixes"}.