GitLint Parser for Node.js

1.1.0 · maintenance · verified Sun Apr 19

Gitlint is a widely used linter for Git commit messages, originally implemented in Python, that enforces conventions such as the Conventional Commits specification, ensuring consistent and readable commit history across projects. The `gitlint-parser-node` package is a JavaScript library designed to parse these commit messages specifically within a Node.js environment, adhering to the core parsing logic and conventions used by gitlint. This enables Node.js applications and tooling to programmatically process, analyze, and extract structured information from git commit messages in a compatible manner, without needing to invoke the Python-based gitlint CLI directly. It supports parsing the various components of a commit message, such as type, scope, subject, body, and footers. The current stable version is 1.1.0. Given its focused utility and version history, it appears to be in a maintenance phase, providing a stable foundation for projects requiring gitlint-compatible commit message parsing in JavaScript.

Common errors

```
TypeError: parse is not a function
```
cause Attempting to use `parse` as a default import (e.g., `import parse from 'gitlint-parser-node'`) when it is exported as a named export.

fix Correct the import statement to use named destructuring: `import { parse } from 'gitlint-parser-node';` for ESM, or `const { parse } = require('gitlint-parser-node');` for CommonJS.
```
Error: Cannot find module 'gitlint-parser-node'
```
cause The package `gitlint-parser-node` has not been installed or is not accessible in the current project's `node_modules`.

fix Install the package using npm: `npm install gitlint-parser-node` or `npm install -g gitlint-parser-node` if it's a global utility.

Warnings

gotcha When consuming `gitlint-parser-node` in a Node.js environment, ensure you use the correct import syntax for your module type. While `require()` is common in older CommonJS projects, modern Node.js applications often use ES Modules (`import`). This package primarily offers named exports.
Fix: For ES Modules, use `import { parse } from 'gitlint-parser-node';`. For CommonJS, use `const { parse } = require('gitlint-parser-node');`.
gotcha As a parsing library, `gitlint-parser-node` expects input formatted according to git commit message conventions. Malformed or unexpectedly structured input may lead to incomplete or incorrect parsing results, or potentially throw errors if the structure deviates too far from expected patterns.
Fix: Validate or sanitize input commit messages before passing them to the `parse` function, especially if the messages come from untrusted or external sources. Handle potential parsing errors gracefully with `try...catch` blocks.

Install

npm install gitlint-parser-node npm
yarn add gitlint-parser-node yarn
pnpm add gitlint-parser-node pnpm

Imports

parse
wrong:
```
const parse = require('gitlint-parser-node');
```
correct:
```
import { parse } from 'gitlint-parser-node';
```
The `parse` function is the primary named export for parsing commit messages. While CommonJS `require` works, ESM `import` is the recommended modern approach.
parse (CommonJS)
wrong:
```
import parse from 'gitlint-parser-node';
```
correct:
```
const { parse } = require('gitlint-parser-node');
```
For CommonJS environments, destructure the `parse` function from the `require` call. Direct default import is not supported as it's a named export.

Quickstart

Demonstrates how to import and use the `parse` function to extract structured data from a conventional git commit message.

import { parse } from 'gitlint-parser-node';

const commitMessage = `feat(parser): add commit message parsing logic\n\nThis commit introduces the initial parsing functionality for git commit messages, adhering to conventional commit guidelines.\n\n- Parses type, scope, subject\n- Extracts body and footers\n\nBREAKING CHANGE: The initial API might change in future minor versions.\nCloses #123, #456`;

try {
  const parsedCommit = parse(commitMessage);
  console.log('Parsed Commit Message:');
  console.log(`Type: ${parsedCommit.type}`);
  console.log(`Scope: ${parsedCommit.scope}`);
  console.log(`Subject: ${parsedCommit.subject}`);
  console.log(`Header: ${parsedCommit.header}`);
  console.log(`Body: ${parsedCommit.body}`);
  console.log('Footers:');
  parsedCommit.footers.forEach(footer => {
    console.log(`  ${footer.token}: ${footer.value}`);
  });
} catch (error) {
  console.error('Failed to parse commit message:', error.message);
}

view raw JSON →