What is @conventional-commits/parser?
@conventional-commits/parser is an npm package designed to parse conventional commit messages. It helps in extracting structured information from commit messages that follow the Conventional Commits specification. This can be useful for generating changelogs, automating versioning, and ensuring commit message consistency.
What are @conventional-commits/parser's main functionalities?
Parse Commit Messages
This feature allows you to parse a conventional commit message and extract structured information such as type, scope, and description.
const parser = require('@conventional-commits/parser');
const commitMessage = 'feat(core): add new feature';
const parsed = parser.sync(commitMessage);
console.log(parsed);
Handle Commit Message with Body and Footer
This feature allows you to parse commit messages that include a body and footer, extracting detailed information including breaking changes.
const parser = require('@conventional-commits/parser');
const commitMessage = 'fix(core): fix bug\n\nThis fixes a critical bug in the core module.\n\nBREAKING CHANGE: This change breaks the API.';
const parsed = parser.sync(commitMessage);
console.log(parsed);
Custom Parser Options
This feature allows you to customize the parser options to fit different commit message patterns.
const parser = require('@conventional-commits/parser');
const commitMessage = 'chore: update dependencies';
const options = { headerPattern: /^( ype)(?: ype)?(?: ype)?$/ };
const parsed = parser.sync(commitMessage, options);
console.log(parsed);
Other packages similar to @conventional-commits/parser
conventional-commits-parser
conventional-commits-parser is another package that parses conventional commit messages. It offers similar functionality to @conventional-commits/parser, allowing you to extract structured information from commit messages. It is widely used in the community and integrates well with other tools in the Conventional Commits ecosystem.
commitizen
commitizen is a tool that helps you write commit messages following the Conventional Commits specification. While it doesn't parse commit messages, it ensures that the messages are formatted correctly, which can then be parsed by tools like @conventional-commits/parser.
semantic-release
semantic-release automates the versioning and package publishing process based on the commit messages. It uses conventional commit messages to determine the type of release (major, minor, patch) and can be used in conjunction with @conventional-commits/parser for parsing commit messages.
Conventional Commits Parser
Reference implementation of Conventional Commits specification.
Outputs a tree structure based on the
unist specification.
Install
npm i @conventional-commits/parser
Usage
const {parser} = require('@conventional-commits/parser')
const ast = parser('feat(parser): add support for scopes')
API
parser(text: string)
Runs conventional commits parser on the string provided.
toConventionalChangelogFormat(ast: object)
Given an object
, representing the parsed commit messages in unist
format,
returns an object useable by the conventional-changelog ecosystem of libraries.
The Grammar
The parser is based on the following grammar. An effort is made to keep this
in sync with the written specification on conventionalcommits.org.
/* See: https://tools.ietf.org/html/rfc3629#section-4 */
<UTF8-char> ::= "Placeholder for UTF-8 grammar"
<UTF8-octets> ::= <UTF8char>+
<CR> ::= "0x000D"
<LF> ::= "0x000A"
<newline> ::= [<CR>], <LF>
<parens> ::= "(" | ")"
<ZWNBSP> ::= "U+FEFF"
<TAB> ::= "U+0009"
<VT> ::= "U+000B"
<FF> ::= "U+000C"
<SP> ::= "U+0020"
<NBSP> ::= "U+00A0"
/* See: https://www.ecma-international.org/ecma-262/11.0/index.html#sec-white-space */
<USP> ::= "Any other Unicode 'Space_Separator' code point"
/* Any non-newline whitespace: */
<whitespace> ::= <ZWNBSP> | <TAB> | <VT> | <FF> | <SP> | <NBSP> | <USP>
<message> ::= <summary>, <newline>+, <body>, (<newline>+, <footer>)*
| <summary>, (<newline>+, <footer>)*
| <summary>, <newline>*
/* "!" should be added to the AST as a <breaking-change> node with the value "!" */
<summary> ::= <type>, "(", <scope>, ")", ["!"], ":", <whitespace>*, <text>
| <type>, ["!"], ":", <whitespace>*, <text>
<type> ::= <any UTF8-octets except newline or parens or ":" or "!:" or whitespace>+
<scope> ::= <any UTF8-octets except newline or parens>+
<text> ::= <any UTF8-octets except newline>*
<body> ::= [<any body-text except pre-footer>], <newline>, <body>*
| [<any body-text except pre-footer>]
/* For convenience the <breaking-change>, <separator>, <whitespace>, and
* <text> tokens of <body-text> should be appended as children to <body> */
<body-text> ::= [<breaking-change>, ":", <whitespace>*], text
/* Note: <pre-footer> is used during parsing, but not returned in the AST. */
<pre-footer> ::= <newline>+, <footer>
<footer> ::= <token>, <separator>, <whitespace>*, <value>
/* "!" should be added to the AST as a <breaking-change> node with the value "!" */
<token> ::= <breaking-change>
| <type>, "(" <scope> ")", ["!"]
| <type>, ["!"]
<separator> ::= ":" | " #"
<value> ::= <text>, <continuation>+
| <text>
<continuation> ::= <newline>, <whitespace>+, <text>
<breaking-change> ::= "BREAKING CHANGE" | "BREAKING-CHANGE"