auto-changelog: Git history rendered as release notes

Why auto-changelog fits tagged repositories

auto-changelog addresses the gap between a project's commit history and a readable release record. It is intended for maintainers who tag releases but do not want to assemble each changelog entry by hand. The tool reads existing Git data rather than introducing a separate issue or release database. That makes it a fit for JavaScript packages whose releases already follow semver naming, especially projects that use tags produced by commands such as npm version.

The README defines two absolute requirements: Git 1.7.2 or later and semver tag names for all versions. Its default tag prefix is v. It also recommends conventional commit messages that close issues and standard merge commit messages from the hosting platform. Those recommendations affect parsing. The command can associate issue references, breaking changes, merges, and pull requests from commit text, so clean history can produce more useful links and classifications.

The project is not an issue tracker and does not decide what happened during development. It reconstructs release notes from tags, commit subjects and bodies, and configured patterns. If a tag contains no useful commits between two versions, or if commit messages omit issue identifiers, auto-changelog cannot manufacture missing release context. Its output is a transformation of repository history, not a replacement for consistent tagging and commit writing.

The Git-to-template data flow

The README states that running auto-changelog invokes git log behind the scenes. Option names also expose a second Git operation for tags, including --append-git-tag for adding arguments to the git tag command. Based on the modules exported by package.json, the implementation separates commits, releases, tags, remotes, templates, command execution, and general utilities under src/. This is a processing pipeline rather than a single formatter.

Tags define version boundaries. Commits are parsed according to include, ignore, issue, breaking-change, and merge patterns. The --commit-pattern option controls what enters generated history, while --ignore-commit-pattern removes matching entries. A release is then associated with commits up to its tag. Unreleased commits can form a separate section, or --package can assign them to the version from package.json.

Rendering is template-driven. The built-in choices named in the README are compact, keepachangelog, and json, with compact as the default. A setup file can be supplied through --handlebars-setup, and plugins can augment commit, merge, and release information. These extension points help when ordinary parsed history is insufficient, but they also add configuration that maintainers must understand before relying on custom output.

Commit ordering defaults to relevance. It can instead use date, date-desc, subject, or subject-desc. By default, each release displays three commits, while empty releases can be backfilled with up to three commits. Setting --commit-limit false disables the per-release limit. These defaults favor a short generated file, but they may hide history when adoption depends on a complete list of changes.

Installing auto-changelog and creating the first file

The README documents global installation as the shortest path. The command must be run from the root of a Git repository. With no output option, it writes to CHANGELOG.md and uses the compact template.

The documented global installation command is:

npm install -g auto-changelog

After installation, run the executable from the repository root:

auto-changelog

The README says the reader should see a generated CHANGELOG.md in the current directory. The command reads the repository's Git history, so an empty result or an unexpected release layout usually points to tag conventions, commit selection, or repository location rather than to a missing installation step.

For project-local automation, the README recommends a development dependency:

npm install auto-changelog --save-dev

The documented package.json configuration uses --package, which takes the latest release from package.json, and stages the generated file during npm version:

{
  "name": "my-awesome-package",
  "version": "1.0.0",
  "devDependencies": {
    "auto-changelog": "*"
  },
  "scripts": {
    "version": "auto-changelog -p && git add CHANGELOG.md"
  }
}

This turns changelog generation into part of the repository's release workflow. It also means that the package manager version and generated file become coupled, so maintainers should review the resulting Markdown before committing it.

Release selection, monorepos, and existing changelogs

auto-changelog offers boundaries for partial history. --starting-version and --ending-version select tags, while --starting-date accepts a yyyy-mm-dd date. --unreleased-only generates only changes that have not reached a release. These controls are useful when a full repository history is too broad or when a maintainer needs a narrower artifact.

Monorepo autodetection is enabled by default according to the option descriptions, although the repository warns that this default will change in the next major version. The paired flags are named --autodetect-monorepo-disabled and --no-autodetect-monorepo-disabled. Their awkward names make the intended state worth checking. Projects whose package layout resembles a monorepo, but which do not want automatic package detection, need to record the chosen option in configuration.

The CLI can preserve an existing hand-written section. Adding the marker <!-- auto-changelog-above --> to a changelog instructs the tool to insert generated content above it while retaining everything below. This is more practical than discarding the entire file, although the README does not describe conflict handling for multiple generators or markers.

Output can also go to stdout through --stdout, which is useful for inspection in a script or terminal. The --prepend option changes how generated content is placed in the output file. For repositories with provider-specific link formats, auto-changelog derives commit, issue, merge, and comparison URLs from GitHub, GitLab, BitBucket, and Azure DevOps remotes. Unusual remotes can use explicit URL templates with {id}, {from}, and {to} tokens.

Configuration and repository trust boundaries

Options can come from package.json or from a configuration file whose default location is .auto-changelog. The README also documents --unsafe-config. Its presence is significant because repository-local configuration can contain options that the command does not trust by default. Automatically running a command that reads configuration from a cloned repository can expose maintainers to settings intended to influence Git command execution or other unsafe behavior.

The project addresses this boundary directly through --unsafe-config, rather than silently trusting all in-repository configuration. That is a sensible default for CI systems and release automation, but it does not make arbitrary repository configuration automatically safe. A maintainer should inspect the effective configuration before enabling this flag, especially in automation that accepts repositories from outside a controlled set.

Two options allow direct extension of Git commands: --append-git-log and --append-git-tag. They are intended for cases where filtering or sorting requires extra Git arguments. This gives the CLI substantial reach over the subprocess commands used to collect history. It also makes escaping and review important when the project handles unusual repository histories.

The template and plugin system adds another configuration surface. A custom template can change presentation, while plugins can add fields to parsed commit, merge, and release data. Neither option guarantees correct classification. The underlying parser still depends on tags and commit messages, so customization should solve a documented formatting or metadata gap rather than compensate for inconsistent repository history.

Limits of Git-derived release notes

The clearest failure mode is a repository that does not follow the required tag convention. The README says all versions should use semver tag names, with a default v prefix. A repository using arbitrary tag names can override the prefix or tag pattern, but the documentation does not claim that every non-semver history can be reconstructed accurately. A release boundary that does not match the expected format may be absent, empty, or assigned incorrectly.

The short default output can also hide relevant changes. Only three commits are displayed per release by default, and empty releases are backfilled with three commits. This is suitable for a concise public changelog, but not for audits, migration guides, or release records that must enumerate every commit. The explicit false value for --commit-limit disables the limit.

Commit messages remain the source of issue links and breaking-change labels. If maintainers write vague subjects, the generated changelog will be vague. The tool does not infer product impact that was never recorded in Git. Likewise, changing default behavior across major versions can alter monorepo detection, so upgrading requires reviewing the generated output rather than assuming a formatting-only change.

For teams that already maintain carefully authored release notes with migration instructions, support impact, or customer-specific context, auto-generated history is the wrong primary source. It can still produce a machine-readable companion, but replacing the hand-maintained document would discard information Git does not contain.

The repository is not archived. Its last push was on 2026-09-27, and it has no GitHub releases. A missing release stream is not proof of inactivity, but it means users cannot rely on GitHub release notes as an upgrade channel. Package installation is the documented acquisition path.

License, runtime, and upgrade obligations

The repository declares the MIT license. That identifies the license recorded by the project, although organizations should review the actual LICENSE.md text and their own compliance obligations rather than treating the label as legal advice.

The current package.json declares Node.js compatibility as ^22.23 || ^24.20 || >= 25.9. This is a concrete adoption constraint for teams still on older Node.js releases, even though the README's basic installation command does not spell it out. The package also exposes the command through the bin entry auto-changelog, while library-style subpaths include src/commits, src/releases, src/remote, src/tags, src/template, src/run, and src/utils.

Upgrades require attention to generated content and option behavior. The repository itself uses a version script that runs the CLI with --package and adds CHANGELOG.md, indicating how its maintainers integrate generation into versioning. The project has no GitHub releases, so compatibility information available to adopters comes from the repository package metadata and source rather than a documented release-note stream.

Users should inspect the package version and Node.js requirement before installation. After an upgrade, regenerate a changelog from a clean working tree and compare it with the previous file, particularly when the repository has custom patterns, plugins, or monorepo detection.

Editorial conclusion

Adopt auto-changelog for a Git repository whose tags, commits, and hosting remotes are already structured well enough for release notes to be derived automatically. Do not choose it for repositories without semver tags, or when every release entry requires facts that exist only in a separate tracker. Before adopting it, inspect CHANGELOG.md in a representative release and verify that issue patterns, breaking change detection, merge parsing, and monorepo autodetection classify the project's history correctly.

Frequently asked questions

Official sources

1. cookpete/auto-changelog on GitHub
2. Issues
3. License: MIT
4. README