npm package: @pajarrahmansyah/commit-changelog
Description: Generate CHANGELOG.md from git commit history (Conventional Commits friendly)
Author: Pajar Rahmansyah
Latest version: 0.1.0

# commit-changelog

Generate `CHANGELOG.md` from git commit history following the [Conventional Commits](https://www.conventionalcommits.org/) specification.

## Features

- Parses Conventional Commits (`feat`, `fix`, `perf`, `revert`, etc.)
- Groups commits by type and scope
- Renders using customizable [Handlebars](https://handlebarsjs.com/) 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

```bash
# 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`.

```bash
# 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

```typescript
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:

```json
{
  "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`](examples/.changelogrc.example.json) for a full reference.

## Custom Templates

Templates use [Handlebars](https://handlebarsjs.com/) 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:**

```hbs
#
{{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](https://www.conventionalcommits.org/):

```
<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](https://github.com/pajarrahmansyah)