parse-commit-message

Extensible parser for git commit messages following Conventional Commits Specification

Please consider following this project's author, Charlike Mike Reagent, and ⭐ the project to show your ❤️ and support.

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.

[!NOTE] Version 4 was skipped since it was long time in canary state, and some are using it. Version 5 is converted to TypeScript, and MAY have breaking changes compared to v4 like higher minimum Node.js version is v20.

Table of Contents

• Install
• API
  • isBreakingChangePlugin
  • mentionsPlugin
  • .parseHeader
  • .stringifyHeader
  • .validateHeader
  • .checkHeader
  • .applyPlugins
  • .plugins
  • .mappers
  • .parseCommit
  • .stringifyCommit
  • .validateCommit
  • .checkCommit
  • .parse
  • .stringify
  • .validate
  • .check
  • incrementPlugin
• Contributing
  • Guides and Community
  • Support the project
• Contributors
• License

(TOC generated by verb using markdown-toc)

Install

This project requires Node.js >=20 (see Support & Release Policy). Install it using yarn or npm.
We highly recommend to use Yarn when you think to contribute to this project.

[!NOTE] This project is written in TypeScript, and exports CJS, ESM, TS, and Types.

$ npm install parse-commit-message

Usage

You can use imports or requires.

import {
  applyPlugins,
  plugins,
  parse,
  stringify,
  check,
  validate,
  plugins,
} from 'parse-commit-message';
// import { parseCommit, stringifyCommit, checkCommit, validateCommit } from 'parse-commit-message/commit';
// import { parseHeader, stringifyHeader, checkHeader, validateHeader } from 'parse-commit-message/header';
// import { normalizeCommit, stringToHeader } from 'parse-commit-message/utils';
// or
const { applyPlugins, plugins, parse, mappers, plugins } = require('parse-commit-message');

You can also import the raw TypeScript source if needed, by importing from parse-commit-message/index.ts

import {
  applyPlugins,
  plugins,
  parse,
  parseHeader,
  parseCommit,
  mappers,
  plugins,
} from 'parse-commit-message/index.ts';

API

Generated using jest-runner-docs.

.parse

Receives and parses a single or multiple commit message(s) in form of string, object, array of strings, array of objects or mixed.

Signature

function(commits: PossibleCommit, options?: Options): Commit[]

Params

• commits {PossibleCommit} - a value to be parsed into an object like Commit type
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Array<Commit>} - if array of commit objects

Examples

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

const commits = [
  'fix(ci): tweaks for @circleci config',
  'chore: bar qux'
];
const result = parse(commits);
console.log(result);
// => [{
//   header: { type: 'fix', scope: 'ci', subject: 'tweaks for @circleci config' },
//   body: null,
//   footer: null,
// }, {
//   header: { type: 'chore', scope: null, subject: 'bar qux' },
//   body: null,
//   footer: null,
// }]

const commitMessage = `feat: awesome yeah

Awesome body!
resolves #123

Signed-off-by: And Footer <[e-mail]>`;

const res = parse(commitMessage);

console.log(res);
// => {
//   header: { type: 'feat', scope: null, subject: 'awesome yeah' },
//   body: 'Awesome body!\nresolves #123',
//   footer: 'Signed-off-by: And Footer <[e-mail]>',
// }

.stringify

Receives a Commit object, validates it using validate, builds a "commit" message string and returns it.

Signature

function(commits: PossibleCommit, options?: Options): string[]

Params

• commits {PossibleCommit} - a Commit object, or anything that can be passed to check
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Array<string>} - an array of commit strings like 'fix(foo): bar baz'

This method does checking and validation too, so if you pass a string, it will be parsed and validated, and after that turned again to string.

Examples

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

const commitMessage = `feat: awesome yeah

Awesome body!
resolves #123

Signed-off-by: And Footer <[e-mail]>`;

const flat = true;
const res = parse(commitMessage, flat);

const str = stringify(res, flat);
console.log(str);
console.log(str === commitMessage);

.validate

Validates a single or multiple commit message(s) in form of string, object, array of strings, array of objects or mixed.

Signature

function(commits: PossibleCommit, options?: Options): Result<Commit[]>

Params

• commits {PossibleCommit} - a value to be parsed & validated into an object like Commit type
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Result} - an object like { value: Array<Commit>, error: Error }

Examples

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

console.log(validate('foo bar qux')); // false
console.log(validate('foo: bar qux')); // true
console.log(validate('fix(ci): bar qux')); // true

console.log(validate(['a bc cqux', 'foo bar qux'])); // false

console.log(validate({ qux: 1 })); // false
console.log(validate({ header: { type: 'fix' } })); // false
console.log(validate({ header: { type: 'fix', subject: 'ok' } })); // true

const commitObject = {
  header: { type: 'test', subject: 'updating tests' },
  foo: 'bar',
  isBreaking: false,
  body: 'oh ah',
};
console.log(validate(commitObject)); // true

const result = validate('foo bar qux');
console.log(result.error);
// => Error: expect \`commit\` to follow:
// <type>[optional scope]: <description>
//
// [optional body]
//
// [optional footer]

const res = validate('fix(ci): okey barry');
console.log(result.value);
// => [{
//   header: { type: 'fix', scope: 'ci', subject: 'okey barry' },
//   body: null,
//   footer: null,
// }]

const commit = { header: { type: 'fix' } };
const { error } = validate(commit);
console.log(error);
// => TypeError: header.subject should be non empty string


const commit = { header: { type: 'fix', scope: 123, subject: 'okk' } };
const { error } = validate(commit);
console.log(error);
// => TypeError: header.scope should be non empty string when given

.check

Receives a single or multiple commit message(s) in form of string, object, array of strings, array of objects or mixed. Throws if find some error. Think of it as "assert", it's basically that.

Signature

function(commits: PossibleCommit, options?: Options): Commit[]

Params

• commits {PossibleCommit} - a value to be parsed & validated into an object like Commit type
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Array<Commit>} - returns the same as given if no problems, otherwise it will throw;

Examples

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

try {
  check({ header: { type: 'fix' } });
} catch(err) {
  console.log(err);
  // => TypeError: header.subject should be non empty string
}

// Can also validate/check a strings, array of strings,
// or even mixed - array of strings and objects
try {
  check('fix(): invalid scope, it cannot be empty')
} catch(err) {
  console.log(err);
  // => TypeError: header.scope should be non empty string when given
}

Generated using jest-runner-docs.

.applyPlugins

Apply a set of plugins over all of the given commits. A plugin is a simple function passed with Commit object, which may be returned to modify and set additional properties to the Commit object.

Params

• plugins {Plugins} - a simple function like (commit) => {}
• commits {PossibleCommit} - a PossibleCommit or an array of strings; a value which should already be gone through parse
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Array<Commit>} - plus the modified or added properties from each function in plugins

The commits should be coming from parse, validate (with ret option) or the check methods. It does not do checking and validation.

Examples

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

const commits = [
  'fix: bar qux',
  dedent`feat(foo): yea yea

  Awesome body here with @some mentions
  resolves #123

  BREAKING CHANGE: ouch!`,
  'chore(ci): updates for ci config',
  {
    header: { type: 'fix', subject: 'Barry White' },
    body: 'okey dude',
    foo: 'possible',
  },
];

// Parses, normalizes, validates
// and applies plugins
const results = applyPlugins(plugins, check(parse(commits)));

console.log(results);
// => [ { body: null,
//   footer: null,
//   header: { scope: null, type: 'fix', subject: 'bar qux' },
//   mentions: [],
//   increment: 'patch',
//   isBreaking: false },
// { body: 'Awesome body here with @some mentions\nresolves #123',
//   footer: 'BREAKING CHANGE: ouch!',
//   header: { scope: 'foo', type: 'feat', subject: 'yea yea' },
//   mentions: [ [Object] ],
//   increment: 'major',
//   isBreaking: true },
// { body: null,
//   footer: null,
//   header:
//    { scope: 'ci', type: 'chore', subject: 'updates for ci config' },
//   mentions: [],
//   increment: false,
//   isBreaking: false },
// { body: 'okey dude',
//   footer: null,
//   header: { scope: null, type: 'fix', subject: 'Barry White' },
//   foo: 'possible',
//   mentions: [],
//   increment: 'patch',
//   isBreaking: false } ]

.plugins

An array which includes mentions, isBreakingChange and increment built-in plugins. The mentions is an array of objects - basically what's returned from the collect-mentions package.

Examples

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

console.log(plugins); // =>  [mentions, increment]
console.log(plugins[0]); // => [Function mentions]
console.log(plugins[1]); // => [Function increment]

const cmts = parse([
  'fix: foo @bar @qux haha',
  'feat(cli): awesome @tunnckoCore feature\n\nSuper duper baz!',
  'fix: ooh\n\nBREAKING CHANGE: some awful api change'
]);

const commits = applyPlugins(plugins, cmts);
console.log(commits);
// => [
//   {
//     header: { type: 'fix', scope: '', subject: 'foo bar baz' },
//     body: '',
//     footer: '',
//     increment: 'patch',
//     isBreaking: false,
//     mentions: [
//       { handle: '@bar', mention: 'bar', index: 8 },
//       { handle: '@qux', mention: 'qux', index: 13 },
//     ]
//   },
//   {
//     header: { type: 'feat', scope: 'cli', subject: 'awesome feature' },
//     body: 'Super duper baz!',
//     footer: '',
//     increment: 'minor',
//     isBreaking: false,
//     mentions: [
//       { handle: '@tunnckoCore', mention: 'tunnckoCore', index: 18 },
//     ]
//   },
//   {
//     header: { type: 'fix', scope: '', subject: 'ooh' },
//     body: 'BREAKING CHANGE: some awful api change',
//     footer: '',
//     increment: 'major',
//     isBreaking: true,
//     mentions: [],
//   },
// ]

.mappers

An object (named set) which includes mentions and increment built-in plugins.

Examples

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

console.log(mappers); // => { mentions, increment }
console.log(mappers.mentions); // => [Function mentions]
console.log(mappers.increment); // => [Function increment]

const flat = true;
const parsed = parse('fix: bar', flat);
console.log(parsed);
// => {
//   header: { type: 'feat', scope: 'cli', subject: 'awesome feature' },
//   body: 'Super duper baz!',
//   footer: '',
// }

const commit = applyPlugins([mappers.increment], parsed);
console.log(commit)
// => [{
//   header: { type: 'feat', scope: 'cli', subject: 'awesome feature' },
//   body: 'Super duper baz!',
//   footer: '',
//   increment: 'patch',
// }]

Generated using jest-runner-docs.

.parseCommit

Receives a full commit message string and parses it into an Commit object and returns it. Basically the same as .parse, except that it only can accept single string.

Signature

function(commit: string, options?: Options): Commit

Params

• commit {string} - a message like 'fix(foo): bar baz\n\nSome awesome body!'
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Commit} - a standard object like { header: Header, body?, footer? }

The parse* methods are not doing any checking and validation, so you may want to pass the result to validateCommit or checkCommit, or to validateCommit with ret option set to true.

Examples

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

const commitObj = parseCommit('foo: bar qux\n\nokey dude');
console.log(commitObj);
// => {
//   header: { type: 'foo', scope: null, subject: 'bar qux' },
//   body: 'okey dude',
//   footer: null,
// }

.stringifyCommit

Receives a Commit object, validates it using validateCommit, builds a "commit" string and returns it. Method throws if problems found. Basically the same as .stringify, except that it only can accept single Commit object.

Signature

function(commit: Commit | BasicCommit, options?: Options): string

Params

• commit {Commit} - a Commit object like { header: Header, body?, footer? }
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {string} - a commit nessage stirng like 'fix(foo): bar baz'

Examples

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

const commitStr = stringifyCommit({
  header: { type: 'foo', subject: 'bar qux' },
  body: 'okey dude',
});
console.log(commitStr); // => 'foo: bar qux\n\nokey dude'

.validateCommit

Validates given Commit object and returns Result. Basically the same as .validate, except that it only can accept single Commit object.

Params

• commit {Commit|BasicCommit} - a Commit like { header: Header, body?, footer? }
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Result} - an object like { value: Array<Commit>, error: Error }

Examples

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

const commit = {
  header: { type: 'foo', subject: 'bar qux' },
  body: 'okey dude',
};

const commitIsValid = validateCommit(commit);
console.log(commitIsValid); // => true

const { value } = validateCommit(commit, true);
console.log(value);
// => {
//   header: { type: 'foo', scope: null, subject: 'bar qux' },
//   body: 'okey dude',
//   footer: null,
// }

.checkCommit

Receives a Commit and checks if it is valid. Method throws if problems found. Basically the same as .check, except that it only can accept single Commit object.

Signature

function(commit: Commit | BasicCommit, options?: Options): Commit

Params

• commit {Commit} - a Commit like { header: Header, body?, footer? }
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Commit} - returns the same as given if no problems, otherwise it will throw.

Examples

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

try {
  checkCommit({ header: { type: 'fix' } });
} catch(err) {
  console.log(err);
  // => TypeError: header.subject should be non empty string
}

// throws because can accept only Commit objects
checkCommit('foo bar baz');
checkCommit(123);
checkCommit([{ header: { type: 'foo', subject: 'bar' } }]);

Generated using jest-runner-docs.

.parseHeader

Parses given header string into an header object. Basically the same as .parse, except that it only can accept single string and returns a Header object.

Signature

function(header: string, options?: Options): Header

Params

• header {string} - a header stirng like 'fix(foo): bar baz'
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Header} - a Header object like { type, scope?, subject }

The parse* methods are not doing any checking and validation, so you may want to pass the result to validateHeader or checkHeader, or to validateHeader with ret option set to true.

Examples

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

const longCommitMsg = `fix: bar qux

Awesome body!`;

const headerObj = parseCommit(longCommitMsg);
console.log(headerObj);
// => { type: 'fix', scope: null, subject: 'bar qux' }

.stringifyHeader

Receives a header object, validates it using validateHeader, builds a "header" string and returns it. Method throws if problems found. Basically the same as .stringify, except that it only can accept single Header object.

Params

• header {Header|SimpleHeader} - a Header object like { type, scope?, subject } or { value: string }
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {string} - a header stirng like 'fix(foo): bar baz'

Examples

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

const headerStr = stringifyCommit({ type: 'foo', subject: 'bar qux' });
console.log(headerStr); // => 'foo: bar qux'

.validateHeader

Validates given header object and returns boolean. You may want to pass ret to return an object instead of throwing. Basically the same as .validate, except that it only can accept single Header object.

Signature

function(header: Header | SimpleHeader, options?: Options)

Params

• header {Header|SimpleHeader} - a Header object like { type, scope?, subject } or { value: string }
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Result} - an object like { value: Array<Commit>, error: Error }

Examples

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

const header = { type: 'foo', subject: 'bar qux' };

const headerIsValid = validateHeader(header);
console.log(headerIsValid); // => true

const { value } = validateHeader(header, true);
console.log(value);
// => {
//   header: { type: 'foo', scope: null, subject: 'bar qux' },
//   body: 'okey dude',
//   footer: null,
// }

const { error } = validateHeader({
  type: 'bar'
}, true);

console.log(error);
// => TypeError: header.subject should be non empty string

.checkHeader

Receives a Header and checks if it is valid. Basically the same as .check, except that it only can accept single Header object.

Signature

function(header: Header | SimpleHeader, options?: Options): Header

Params

• header {Header|SimpleHeader} - a Header object like { type, scope?, subject } or { value: string }
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Header} - returns the same as given if no problems, otherwise it will throw.

Examples

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

try {
  checkHeader({ type: 'fix' });
} catch(err) {
  console.log(err);
  // => TypeError: header.subject should be non empty string
}

// throws because can accept only Header objects
checkHeader('foo bar baz');
checkHeader(123);
checkHeader([]);
checkHeader([{ type: 'foo', subject: 'bar' }]);

Generated using jest-runner-docs.

isBreakingChangePlugin

A plugin that adds isBreakingChange and isBreaking (deprecated) properties to the commit. It is already included in the plugins named export, and in mappers named export. Be aware that there's a difference between the utility isBreakingChange which has named export (as everything from src/utils) and this plugin function.

Note: This plugin was included in v4 release version, previously was part of the increment plugin.

Signature

function(commit: Commit, options?: Options)

Params

• commit {Commit} - a standard Commit object
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Commit} - plus { isBreakingChange: boolean }

See the .plugins and .mappers examples.

Examples

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

console.log(mappers.isBreakingChange); // => [Function: isBreakingChangePlugin]
console.log(plugins[2]); // => [Function: isBreakingChangePlugin]

Generated using jest-runner-docs.

mentionsPlugin

A plugin that adds mentions array property to the commit. It is already included in the plugins named export, and in mappers named export. Basically each entry in that array is an object, directly returned from the collect-mentions.

Signature

function(commit: Commit, options?: Options): { mentions: Mention[] }

Params

• commit {Commit} - a standard Commit object
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Commit} - plus { mentions: Array<Mention> }

See the .plugins and .mappers examples.

Examples

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

console.log(mappers.mentions); // => [Function: mentionsPlugin]
console.log(plugins[0]); // => [Function: mentionsPlugin]

Generated using jest-runner-docs.

incrementPlugin

A plugin that adds increment property to the commit. It is already included in the plugins named export, and in mappers named export.

Note: Since v4 this plugin doesn't add isBreaking property, use the isBreaking plugin instead.

Params

• commit {Commit} - a standard Commit object
• options {object} - options to control the header regex and case sensitivity
• options.headerRegex {RegExp|string} - string regular expression or instance of RegExp
• options.caseSensitive {boolean} - whether or not to be case sensitive, defaults to false
• returns {Commit} - plus { increment: 'major' | 'minor' | 'patch' | '' }

See the .plugins and .mappers examples.

Examples

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

console.log(mappers.increment); // => [Function: incrementPlugin]
console.log(plugins[1]); // => [Function: incrementPlugin]

back to top

Contributing

Guides and Community

Please read the Contributing Guide and Code of Conduct documents for advices.

For bug reports and feature requests, please join our community forum and open a thread there with prefixing the title of the thread with the name of the project if there's no separate channel for it.

Consider reading the Support and Release Policy guide if you are interested in what are the supported Node.js versions and how we proceed. In short, we support latest two even-numbered Node.js release lines.

Support the project

Become a Partner or Sponsor? 💵 Check the OpenSource Commision (tier). 🎉 You can get your company logo, link & name on this file. It's also rendered on package's page in npmjs.com and yarnpkg.com sites too! 🚀

Not financial support? Okey! Pull requests, stars and all kind of contributions are always welcome. ✨

Contributors

This project follows the all-contributors specification. Contributions of any kind are welcome!

Thanks goes to these wonderful people (emoji key), consider showing your support to them:

Charlike Mike Reagent 🚇 💻 📖 🤔 🚧 ⚠️

back to top

License

Copyright (c) 2018-present, Charlike Mike Reagent <[e-mail]> & contributors.
Released under the MPL-2.0 License.