Parse-commit-message NPM

parse-commit-message

An extensible parser for commit message that follows Conventional Commits v1 spec

If you have any how-to kind of questions, please read the Contributing Guide and Code of Conduct documents.
For bugs reports and feature requests, please create an issue or ping @tunnckoCore at Twitter.

Project is semantically & automatically released on CircleCI with new-release and its New Release GitHub App.

Highlights

Conventional Commits compliant
Fast and lightweight in few lines of code
Infinitely extensible through plugins, two built-in
Collecting mentions from commit message
Detection of breaking changes in commit

Install

This project requires Node.js ^6.9.0 || ^8.9.0 || ^10.6.0. Install it using yarn or npm.
We highly recommend to use Yarn when you think to contribute to this project.

$ yarn add parse-commit-message

API

.parse

Parses given commitMessage to an object which can be populated with more things if needed, through plugins.

Plugins are functions like (commit) => {} and can return object with additional properties that will be included in the returned "commit" object. There are two built-in plugins - increment and mentions which are exposed as array at exposed plugins named export. The commit.header has also a toString() method concatinates the header.scope, header.type and header.subject properties.

Params

commitMessage {string}: required, a whole commit message
plugins {Array}: optional, a list of functions that are passed with commit object
returns {Object}: with { header: { type, scope, subject }, body, footer }

Example

import { parse } from 'parse-commit-message';

const commit = parse(`fix(crit): some huge change

Some awesome
body here.

resolves #333
`);

console.log(commit)
// => {
//   header: {
//     type: 'fix',
//     scope: 'crit',
//     subject: 'some huge change'
//     toString: [Function: toString],
//   },
//   body: 'Some awesome\nbody here.',
//   footer: 'resolves #333',
// }

console.log(commit.header.toString())
// => 'fix(crit): some huge change'

// or adding one more plugin to the builtin ones
const customPlugin = (commit) => {
  if (commit.header.type === 'fix') {
    return { fixed: 'yeah' };
  }
  return null;
};
const commit = parse('fix(wat): foo bar baz', plugins.concat(customPlugin));

console.log(commit.isBreaking) // => false
console.log(commit.increment) // => 'patch'
console.log(commit.header); // => { type: 'fix', subject: 'wat', subject: 'foo bar baz' }
console.log(commit.fixed); // => 'yeah'

.mappers

An object with all mappers, such as plugins array, but named. This objects is like { increment, mentions } where they are plugins that can be passed as second argument to .parse.

The mappers.increment adds isBreaking and increment properties to the final returned "commit" object:

isBreaking is Boolean that indicates if commit is containing BREAKING CHANGE: or the type of the commit is break, breaking or major
increment is a String that can be 'patch', 'minor' or 'major'

The mappers.mentions adds mentions property to the end result object

mentions is an array of objects like { handle: String, mention: String, index: Number }, see collect-mentions

Example

import { parse, mappers } from 'parse-commit-message';

const commit = parse('fix: BREAKING CHANGE: huge refactor', mappers.increment);

console.log(commit);
// => {
//   header: { type: 'fix', scope: undefined, subject: 'BREAKING CHANGE: huge refactor' },
//   body: null,
//   footer: null,
//   isBreaking: true,
//   increment: 'major'
// }

const str = `feat(whoa): thanks to @foobie for this

awesome @zazzy and @quxie make this release to happen

resolves #123
`
const cmt = parse(str, mappers.mentions);

console.log(cmt.header.type); // => 'feat'
console.log(cmt.header.scope); // => 'whoa'
console.log(cmt.header.subject); // => 'hanks to @foobie for this'
console.log(cmt.body); // => 'awesome @zazzy and @quxie make this release to happen'
console.log(cmt.footer); // => 'resolves #123'
console.log(cmt.mentions[0]); // => { handle: '@foobie', mention: 'foobie' }
console.log(cmt.mentions[1]); // => { handle: '@zazzy', mention: 'zazzy' }
console.log(cmt.mentions[2]); // => { handle: '@quxie', mention: 'quxie' }

.plugins

A list of all plugins, such as mappers but no names, so can be passed directly to the .parse as second argument.

Example

import { parse, plugins } from 'parse-commit-message';

const commit = parse('fix: okey', plugins)
console.log(commit)

back to top

Related Projects

Some of these projects are used here or were inspiration for this one, others are just related. So, thanks for your existance!

asia: Blazingly fast, magical and minimalist testing framework, for Today and Tomorrow | homepage
charlike: Small, fast, simple and streaming project scaffolder for myself, but not… more | homepage
collect-mentions: Collect mentions from a given text string, using battle-tested mentions-regex package | homepage
gitcommit: Lightweight and joyful git commit replacement. Conventional Commits compliant. | homepage
new-release: A stable alternative to semantic-release. Only handles NPM publishing and nothing… more | homepage
xaxa: Zero-config linting, powered by few amazing unicorns, AirBnB & Prettier. | homepage

back to top

Contributing

Please read the Contributing Guide and Code of Conduct documents for advices.
For bugs reports and feature requests, please create an issue or ping @tunnckoCore at Twitter.

Contributors

Thanks to the hard work of these wonderful people this project is alive and it also follows the all-contributors specification.
Pull requests, stars and all kind of contributions are always welcome. :stars:

Users

You can see who uses parse-commit-message in the USERS.md file. Please feel free adding this file if it not exists.
If you or your organization are using this project, consider adding yourself to the list of users.
Thank You! :heart: