git-changelog-kit

A strict TypeScript library for generating changelogs from Git history and Conventional Commits.

Features

• reads commit history from a local Git repository;
• parses the raw git log format;
• supports Conventional Commits and breaking-change markers;
• groups commits into changelog sections;
• generates deterministic Markdown;
• exposes typed errors and strict public types;
• ships as a native ESM package with TypeScript declarations.

Requirements

• Node.js 20.19 or newer;
• a Git executable available in PATH.

Installation

npm install --save-dev git-changelog-kit

Quick start

Create scripts/generate-changelog.mjs in your project:

import { writeFile } from 'node:fs/promises';

import {
  formatChangelogAsMarkdown,
  generateChangelog,
  parseConventionalCommit,
  parseGitLog,
  readGitLog,
} from 'git-changelog-kit';

const rawLog = await readGitLog({
  cwd: process.cwd(),
  from: 'v1.0.0',
  to: 'HEAD',
});

const commits = parseGitLog(rawLog).map(parseConventionalCommit);
const changelog = generateChangelog(commits, {
  title: 'Changelog',
  version: '1.1.0',
});
const markdown = formatChangelogAsMarkdown(changelog);

await writeFile('CHANGELOG.md', markdown, 'utf8');

Add a package script:

{
  "scripts": {
    "changelog": "node scripts/generate-changelog.mjs"
  }
}

Then run:

npm run changelog

Git log options

readGitLog() supports:

const rawLog = await readGitLog({
  cwd: process.cwd(),
  from: 'v1.0.0',
  to: 'HEAD',
  since: '2026-01-01',
  until: '2026-07-04',
  author: 'Oleg Yurin',
  maxCount: 100,
});

All options are optional. Without cwd, the current working directory is used.

Library pipeline

The API is intentionally split into testable stages:

readGitLog
  -> parseGitLog
  -> parseConventionalCommit
  -> generateChangelog
  -> formatChangelogAsMarkdown

This makes it possible to replace any stage or provide commits from another source.

Error handling

Git failures are exposed as GitLogError with one of these codes:

• NOT_GIT_REPOSITORY;
• EMPTY_REPOSITORY;
• INVALID_REVISION_RANGE;
• GIT_COMMAND_FAILED.

import { GitLogError, readGitLog } from 'git-changelog-kit';

try {
  await readGitLog();
} catch (error) {
  if (error instanceof GitLogError) {
    console.error(error.code, error.gitMessage);
  }
}

Current limitations

• the Git reader currently loads the commit subject but not the full body;
• body-based BREAKING CHANGE detection is available in the API but requires the caller to provide body text;
• the CLI entry currently exposes help and version only; changelog generation is available through the library API.

Local package testing

Build and create a local npm tarball:

npm install
npm run check
npm pack

Install that tarball in another project:

npm install --save-dev /path/to/git-changelog-kit-0.1.0.tgz

Development

npm install
npm run check

Useful commands:

• npm run build — build ESM and TypeScript declarations with tsup;
• npm test — run unit and snapshot tests with Vitest;
• npm run typecheck — validate strict TypeScript types;
• npm run lint — run ESLint;
• npm run format:check — check formatting with Prettier;
• npm run pack:check — inspect the npm package contents.

License

MIT