commit-changelog

Generate CHANGELOG.md from git commit history following the Conventional Commits specification.

Features

• Parses Conventional Commits (feat, fix, perf, revert, etc.)
• Groups commits by type and scope
• Renders using customizable Handlebars templates
• Supports BREAKING CHANGE detection
• Works as a CLI tool and a Node.js library
• Config via .changelogrc.json, .changelogrc.yaml, or package.json

Installation

# Global CLI
npm install -g @pajarrahmansyah/commit-changelog

# Or as a dev dependency
npm install --save-dev @pajarrahmansyah/commit-changelog

CLI Usage

Two commands are available: commit-changelog and the short alias ccl.

# Generate CHANGELOG.md (auto-detects latest git tag as start)
ccl generate

# Specify output file
ccl generate MY_CHANGELOG.md

# Specify a git range
ccl generate --from v1.0.0 --to v2.0.0

# Preview without writing (dry run)
ccl generate --dry-run

# Use a custom config file
ccl generate --config ./my-config.json

# Use a custom Handlebars template
ccl generate --template ./my-template.hbs

CLI Flags

| Flag | Short | Default | Description | | ------------------- | ----- | ---------------- | ---------------------------------- | | --from <ref> | | latest git tag | Start git ref (tag or commit hash) | | --to <ref> | | HEAD | End git ref | | --config <path> | -c | auto-detected | Path to config file | | --template <path> | -t | built-in default | Path to .hbs template | | --dry-run | | false | Print to stdout, don't write file | | --version | -v | | Print version |

Tip: ccl is a short alias for commit-changelog — both commands are identical.

Library Usage

import {
  generate,
  getCommits,
  parseCommitsPublic,
} from "@pajarrahmansyah/commit-changelog";

// Generate a changelog file
const result = await generate({
  outputPath: "CHANGELOG.md",
  fromRef: "v1.0.0",
  toRef: "HEAD",
});
console.log(result.changelog);

// Get raw commits
const rawCommits = getCommits({ fromRef: "v1.0.0" });

// Parse commits
const parsed = parseCommitsPublic(rawCommits);

generate(options)

| Option | Type | Default | Description | | -------------- | --------- | ---------------- | ----------------------- | | outputPath | string | 'CHANGELOG.md' | Output file path | | configPath | string | auto-detect | Path to config file | | fromRef | string | latest git tag | Start git ref | | toRef | string | 'HEAD' | End git ref | | templatePath | string | built-in | Path to .hbs template | | dryRun | boolean | false | Skip writing file |

Returns Promise<{ path: string; changelog: string }>.

Configuration

Create a .changelogrc.json (or .changelogrc.yaml) in your project root:

{
  "types": {
    "feat": { "title": "Features" },
    "fix": { "title": "Bug Fixes" },
    "perf": { "title": "Performance Improvements" },
    "docs": { "title": "Documentation", "hidden": false },
    "chore": { "title": "Chores", "hidden": true }
  },
  "scopeOrder": ["api", "cli", "core"],
  "groupOrder": ["feat", "fix", "perf"],
  "parserOptions": {
    "noteKeywords": ["BREAKING CHANGE", "BREAKING-CHANGE"]
  }
}

You can also add a "changelog" key to your package.json with the same structure.

See examples/.changelogrc.example.json for a full reference.

Custom Templates

Templates use Handlebars syntax. The default template is at templates/default.hbs.

Available context:

header      — string: "Changelog"
version     — string: from package.json, e.g. "1.2.0"
date        — string: ISO date, e.g. "2026-03-10"
sections[]
  .title    — string: "Features"
  .type     — string: "feat"
  .scopes
    [scope] — CommitEntry[]
      .description  — string
      .hash         — string (short)
      .author       — string
      .breaking     — boolean

Example custom template:

#
{{header}}

##
{{version}}
—
{{date}}

{{#each sections}}
  ###
  {{this.title}}
  {{#each this.scopes}}
    **{{@key}}**
    {{#each this}}
      -
      {{this.description}}
      (`{{this.hash}}`) —
      {{this.author}}
    {{/each}}
  {{/each}}
{{/each}}

Commit Format

Follows Conventional Commits:

<type>(<scope>): <subject>

[optional body]

[optional footer: BREAKING CHANGE: description]

Examples:

feat(api): add support for pagination
fix(cli): handle missing git tags gracefully
feat!: drop support for Node 12
fix: correct typo in error message

BREAKING CHANGE: removed legacy --output flag

License

MIT © Pajar Rahmansyah