changelog

Changelog is a CLI tool for managing changelogs. Individual changelog entries are stored as files, eliminating merge conflicts and enabling CI enforcement.

Full documentation

Installation

npm

Install globally:

npm install -g @d-dev/changelog

Or as a dev dependency:

npm install -D @d-dev/changelog

Or run with npx

npx @d-dev/changelog

PyPI

Install with pip:

pip install changesets

Install with uv.

uv tool install changesets

Or as a dev dependency

uv add --dev changesets

Or run directly with uvx (no install required):

uvx --from changesets changelog <command>

GitHub Releases

Download pre-built binaries from GitHub Releases.

Available platforms:

Initialize

Run changelog init in your project root to set up the .changelog directory:

changelog init

You'll be prompted for:

? Current version: 0.1.0
? Changelog file path: CHANGELOG.md
? Main git branch: main
Enter post-apply commands (leave blank to finish):
? Post-apply command: npm install
? Post-apply command (1 added):
✓ Initialized .changelog directory

This creates the following structure:

.changelog/
├── config.yaml
├── next/
│   └── .gitkeep
├── releases/
│   └── .gitkeep
└── templates/
    ├── header.md
    ├── body.eta
    └── footer.md

Add an Entry

When you make a notable change, run changelog add:

changelog add

Select a change type and provide a description:

? Change type: Add - Add a new feature. Minor version bump.
? Description: Support for YAML configuration files
✓ Added changelog entry: .changelog/next/1740000000000.yaml
✓ Updated CHANGELOG.md

A YAML file is created in .changelog/next/:

timestamp: 1740000000000
type: Add
description: Support for YAML configuration files

The changelog file is automatically regenerated with an Unreleased section so you can preview changes at any time.

Apply a Release

When you're ready to release, run changelog apply:

changelog apply

This computes the version bump, creates the release, and updates your project:

✓ Updated version in package.json to 0.2.0
✓ Applied version 0.2.0
✓ Updated CHANGELOG.md
Running post-apply command: npm install
? Commit changes and tag the commit? Yes
✓ Committed and tagged version 0.2.0

The version bump is determined by the change types present:

After applying, push the commit and tag:

git push origin main --follow-tags

Full documentation