Package: conventional
ConventionalConventional is an extensible command-line tool for parsing and processing structured commits. It comes with support for theConventional Commitsstandard, but can be extended to support any other commit formats.SeeCHANGELOG.mdfor an example of the kind of features supported by this tool.RequirementsPython 3.8+Git 2.27.0InstallationInstall and update usingpip:$pipinstall-UconventionalUsageListing Commits$conventionallist-commitsThelist-commitscommand will retrieve git commits from a repository and output them in json, one object per commit per line, which can then be piped to, eg.,jq. By default the command will output the raw fields retrieved from the commit, including the commit's subject, body, author, and date.This command can automatically parse commits by providing the--parseflag. If the flag is specified, commits will be instead output in the format described inParsing Commits. The--include-unparsedflag is supported in this command as will, and if provided commits which failed to be parsed will be output missing thedatafield.Parsing Commits$conventional[--config.conventional.yaml]parse-commitTheparse-commitcommand will read commits from a file or stdin and attempt to parse them using the configured parser. This command will output commits in json, one object per line, in the format{"source": {}, "data": {}}, wheresourcecontains the raw commit fields anddatacontains the fields parsed from the commit.If a commit cannot be parsed, by default it will not be included in the output. This behaviour can be disabled with the--include-unparsedflag, in which case commits that fail to be parsed will be output missing thedatafield (as no fields could be parsed).SeeParsersbelow for a list of parsers included withconventional.Rendering commits into a template$conventional[--config.conventional.yaml]templateThetemplatecommand will read a stream of commits, determine different "versions" by looking at the tags on commits, and render them using the configured template. Templates are rendered using Jinja2, and are provided the list of versions along with any custom configuration specified in the configuration file.SeeTemplatesbelow for a list of templates included withconventional.NotesInternally, some commands will use other commands to provide additional functionality and simplify common use-cases.For example...$conventionallist-commits--parse# is equivalent to$conventionallist-commits|conventionalparse-commitAnd...$conventionaltemplate# is equivalent to$conventionallist-commits|conventionalparse-commit|conventionaltemplate--input-This means that if, for example, you wish to useconventional templatebut only use commits created since the last tag you can use the commandconventional list-commits --from-last-tag | conventional template --input -.ConfigurationAlong with the command-line parameters, a configuration file can be provided via the--config-fileparameter when callingconventional. By defaultconventionalis configured to parse commits aligning to theConventional Commitsstandard and render them into a changelog, but this can be changed by configuring theparserandtemplatesections in the config file, along with other things.Seeconfig_default.yamlto see what can be included in the configuration file.Below is a list of the parsers and templates provided by default withconventional.Parsersmodule: conventional.parser, name: ConventionalCommitParserParses commits aligning to theConventional Commitsstandard.Supported configuration:types- The values which are allowed to be used as atypein commit messages. Any commits using a type not specified in this list will fail to parse correctly.Templatespackage: conventional, name: changelog.mdRenders commits in a format appropriate for a storing in a CHANGELOG.md file.Supported configuration:commit-link-pattern- This pattern will be used to generate a link to the commit, with{rev}being replaced with the hash of the commit and{short_rev}being replace with the short hash of the commit. For example, if you are using Github this may behttps://github.com/[owner]/[repo]/commit/{rev}.compare-link-pattern- This pattern will be used to generate a link to a comparison between the current version and the previous version, with{to}being replaced with the tag of the current version and{from}being replaced with the tag of the previous version. For example, in Github this may behttps://github.com/[owner]/[repo]/compare/{from}...{to}issue-link-pattern- This pattern will be used to generate a link to any issues references in the commit, with{issue}being expanded to the ID of the issue. For example, if you are using Jira this format may behttps://[company].atlassian.net/browse/{issue}.version-link-pattern- This pattern will be used to generate a link to the source for a given version, with{tag}being replaced by the tag for the given version. For example, in Github this may behttps://github.com/[owner]/[repo]/tree/{tag}type-headings- A mapping of commit "type" to the text that should be used in the header for a specific type of change. Defaults to{"feat": "Feature", "fix": "Fixes"}.package: conventional, name: slack.mdRenders commits in a format appropriate for posting to Slack.Supported configuration:commit-link-pattern- This pattern will be used to generate a link to the commit, with{rev}being replaced with the hash of the commit and{short_rev}being replace with the short hash of the commit. For example, if you are using Github this may behttps://github.com/[owner]/[repo]/commit/{rev}.compare-link-pattern- This pattern will be used to generate a link to a comparison between the current version and the previous version, with{to}being replaced with the tag of the current version and{from}being replaced with the tag of the previous version. For example, in Github this may behttps://github.com/[owner]/[repo]/compare/{from}...{to}issue-link-pattern- This pattern will be used to generate a link to any issues references in the commit, with{issue}being expanded to the ID of the issue. For example, if you are using Jira this format may behttps://[company].atlassian.net/browse/{issue}.version-link-pattern- This pattern will be used to generate a link to the source for a given version, with{tag}being replaced by the tag for the given version. For example, in Github this may behttps://github.com/[owner]/[repo]/tree/{tag}type-headings- A mapping of commit "type" to the text that should be used in the header for a specific type of change. Defaults to{"feat": "Feature", "fix": "Fixes"}.