commit-parser

A tiny parser for conventional commits that extracts metadata like type, scope, breaking changes and references.

Installation

npm install commit-parser

Usage

[!NOTE] As of version 1.0.0, this library uses quansync to provide both async and sync APIs. The default API is async (non-blocking), with a .sync() method available for synchronous usage.

Async API (Default)

import { getCommits, getRawGitCommitStrings } from "commit-parser";

// get and parse all commits between two git references (async)
const commits = await getCommits({ from: "v1.0.0", to: "v2.0.0" });

// or get commits up to a specific reference
const recentCommits = await getCommits({ to: "main" });

// get raw commit strings
const rawCommits = await getRawGitCommitStrings({ from: "v1.0.0", to: "v2.0.0" });

Sync API

If you need synchronous execution (blocks the event loop), use the .sync() method:

import { getCommits, getRawGitCommitStrings } from "commit-parser";

// synchronous version
const commits = getCommits.sync({ from: "v1.0.0", to: "v2.0.0" });
const rawCommits = getRawGitCommitStrings.sync({ from: "v1.0.0", to: "v2.0.0" });

Parsing Commits

const rawCommit = "abc123|feat: add new feature|John Doe|[email protected]|1609459200";
const parsedRawCommit = parseRawCommit(rawCommit);
// {
//   shortHash: "abc123",
//   message: "feat: add new feature",
//   author: {
//     name: "John Doe",
//     email: "[email protected]"
//   },
//   date: "1609459200",
//   body: ""
// }

// parse with additional conventional commit metadata
const parsedCommit = parseCommit(parsedRawCommit);
// {
//   shortHash: "abc123",
//   message: "feat: add new feature",
//   authors: [{
//     name: "John Doe",
//     email: "[email protected]"
//   }],
//   date: "1609459200",
//   body: "",
//   type: "feat",
//   scope: "",
//   description: "add new feature",
//   isBreaking: false,
//   isConventional: true,
//   references: []
// }

// handles breaking changes
const breakingCommit = parseRawCommit("def456|feat!: breaking change|Jane Doe|[email protected]|1609459200");
const parsedBreaking = parseCommit(breakingCommit);
// isBreaking will be true

// extracts PR and issue references
const commitWithRefs = parseRawCommit("ghi789|fix: resolve crash, closes #123 (#456)|Dev User|[email protected]|1609459200");
const parsedRefs = parseCommit(commitWithRefs);
// references will contain [{ type: "pull-request", value: "#456" }, { type: "issue", value: "#123" }]

// handles co-authors
const coAuthoredCommit = parseRawCommit("jkl012|feat: collaborative feature|Main Author|[email protected]|1609459200|Some description\n\nCo-authored-by: Contributor One <[email protected]>");
const parsedCoAuthored = parseCommit(coAuthoredCommit);
// authors will contain both the main author and co-author

📄 License

Published under MIT License.

Acknowledgements

This project is using code from unjs/changelogen, which is licensed under the MIT License