auto-changelog

auto-changelog

Command line tool for generating a changelog from git tags and commit history. Used by Modernizr, Netlify, Neutrino and Velocity.js.

Installation

npm install -g auto-changelog

Usage

Simply run auto-changelog in the root folder of a git repository. git log is run behind the scenes in order to parse the commit history.

…

Requirements

auto-changelog is designed to be as flexible as possible, providing a clear changelog for any project. There are only two absolute requirements:

• You should be using git 1.7.2 or later
• All versions should be tagged using semver tag names – this happens by default when using npm version

There are some less strict requirements to improve your changelog:

• Close issues using keywords
• Merge pull requests using the standard merge commit message for your platform

What you might do if you’re clever

Install auto-changelog to dev dependencies:

npm install auto-changelog --save-dev
# or
yarn add auto-changelog --dev

Add auto-changelog -p && git add CHANGELOG.md to the version scripts in your package.json:

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

Using -p or --package uses the version from package.json as the latest release, so that all commits between the previous release and now become part of that release. Essentially anything that would normally be parsed as Unreleased will now come under the version from package.json

Now every time you run npm version, the changelog will automatically update and be part of the version commit.

Advanced Usage

URL Overrides

Links to commits, issues, pull requests and version diffs are automatically generated based on your remote URL. GitHub, GitLab, BitBucket and Azure DevOps are all supported. If you have an unusual remote or need to override one of the link formats, use --commit-url, --issue-url or --merge-url with an {id} token. For custom version diffs, use --compare-url with {from} and {to} tokens.

# Link all issues to redmine
auto-changelog --issue-url https://www.redmine.org/issues/{id}

# Link to custom diff page
auto-changelog --compare-url https://example.com/repo/compare/{from}...{to}

Add to an existing changelog

If you’d like to keep an existing changelog below your generated one, just add `` to your current changelog. The generated changelog will be added above this token, and anything below will remain.

Configuration

You can set any option in package.json under the auto-changelog key, using camelCase options.

{
  "name": "my-awesome-package",
  "version": "1.0.0",
  "scripts": {
    // ...
  },
  "auto-changelog": {
    "output": "HISTORY.md",
    "template": "keepachangelog",
    "unreleased": true,
    "commitLimit": false
  }
}

You can also store config options in an .auto-changelog file in your project root:

{
  "output": "HISTORY.md",
  "template": "keepachangelog",
  "unreleased": true,
  "commitLimit": false
}

Note that any options set in package.json will take precedence over any set in .auto-changelog.

Security and untrusted repositories

auto-changelog is sometimes run over repository content that you do not control - for example a CI job that checks out an untrusted pull request, or generating a changelog for a third-party repo on your own machine. Because the .auto-changelog file and the package.json auto-changelog key live inside that repository, they are treated as untrusted input. If in-repo config sets an option that could load code, inject extra git arguments, write outside the repository, or make a network request, auto-changelog refuses to run and exits with an error rather than silently ignoring the value.

These options can never come from in-repo config, because no value is safe - pass them as command line flags instead:

• --handlebars-setup (loads a JS file via require)
• --plugins (loads a JS module via require)
• --template, when it is a URL (fetched over the network)

These options are honored from in-repo config, but a value that would do one of the unsafe things above is rejected:

• remote/--remote is used in a git command, so a value containing whitespace (which would inject extra git arguments) is rejected; ordinary remote names like upstream are fine.
• output/--output is a write path, so an absolute path or one containing .. (which could write outside the repository) is rejected; ordinary in-repo paths like HISTORY.md are fine.
• --append-git-log and --append-git-tag are appended to the git commands, so a value containing --output (which would write to an arbitrary file) is rejected; ordinary arguments like --first-parent are fine.

In every case, "rejected" means auto-changelog stops with an error - it never silently drops the value or produces a changelog from sanitized config. If you fully trust the repository you are running against and want to honor its config as-is, pass --unsafe-config. Do not use --unsafe-config with repositories you do not control.

Tag prefixes

Use --tag-prefix [prefix] if you prefix your version tags with a certain string:

# When all versions are tagged like my-package/1.2.3
auto-changelog --tag-prefix my-package/

Monorepos

In a monorepo, each package's version tags are typically prefixed with the package name, like [email protected]. When monorepo autodetection is enabled, auto-changelog detects a monorepo package - by a repository.directory field in package.json, or an ancestor package.json declaring npm workspaces - and, for a detected package:

• derives the tag prefix from the name in package.json (so you don't have to set --tag-prefix for every package), unless one is already configured, and
• strips that prefix from the release titles in the changelog (so headings read ## [1.2.3] rather than ## [[email protected]]), while still using the full tags for the compare links.

Autodetection is controlled by --autodetect-monorepo-disabled, which defaults to true. To opt in today, set it to false:

{
  "auto-changelog": {
    "autodetectMonorepoDisabled": false
  }
}

This option will default to false in the next major version, enabling monorepo autodetection out of the box.

Tag patterns

By default, auto-changelog looks for valid semver tags to build a list of releases. If you are using another format (or want to include all tags), use --tag-pattern [regex]:

# When all versions are tagged like build-12345
auto-changelog --tag-pattern build-\d+

# Include any tag as a release
auto-changelog --tag-pattern .+

Breaking changes

If you use a common pattern in your commit messages for breaking changes, use --breaking-pattern to highlight those commits as breaking changes in your changelog. Breaking change commits will always be listed as part of a release, regardless of any --commit-limit set.

auto-changelog --breaking-pattern "BREAKING CHANGE:"

Custom issue patterns

By default, auto-changelog will parse GitHub-style issue fixes in your commit messages. If you use Jira or an alternative pattern in your commits to reference issues, you can pass in a custom regular expression to --issue-pattern along with --issue-url:

# Parse Jira-style issues in your commit messages, like PROJECT-418
auto-changelog --issue-pattern [A-Z]+-\d+ --issue-url https://issues.apache.org/jira/browse/{id}

Or, in your package.json:

{
  "name": "my-awesome-package",
  "auto-changelog": {
    "issueUrl": "https://issues.apache.org/jira/browse/{id}",
    "issuePattern": "[A-Z]+-\d+"
  }
}

If you use a certain pattern before or after the issue number, like fixes {id}, just use a capturing group:

# "This commit fixes ISSUE-123" will now parse ISSUE-123 as an issue fix
auto-changelog --issue-pattern "[Ff]ixes ([A-Z]+-\d+)"

Custom templates

If you aren’t happy with the default templates or want to tweak something, you can point to a handlebars template in your local repo. Check out the existing templates to see what is possible.

Save changelog-template.hbs somewhere in your repo:

…

Then just use --template to point to your template:

auto-changelog --template changelog-template.hbs

You can also point to an external template by passing in a URL:

auto-changelog --template https://example.com/templates/compact.hbs

A URL template is fetched over the network, so it can only be passed on the command line; setting template to a URL in in-repo config makes auto-changelog refuse to run (see Security).

To see exactly what data is passed in to the templates, you can generate a JSON version of the changelog:

auto-changelog --template json --output changelog-data.json

commit-list helper

Use {{#commit-list}} to render a list of commits depending on certain patterns in the commit messages:

{{#each releases}}
  ### [{{title}}]({{href}})

  {{! List commits with `Breaking change: ` somewhere in the message }}
  {{#commit-list commits heading='### Breaking Changes' message='Breaking change: '}}
    - {{subject}} [`{{shorthash}}`]({{href}})
  {{/commit-list}}

  {{! List commits that add new features, but not those already listed above }}
  {{#commit-list commits heading='### New Features' message='feat: ' exclude='Breaking change: '}}
    - {{subject}} [`{{shorthash}}`]({{href}})
  {{/commit-list}}
{{/each}}

Replacing text

To insert links or other markup to PR titles and commit messages that appear in the log, use the replaceText option in your package.json:

{
  "name": "my-awesome-package",
  "auto-changelog": {
    "replaceText": {
      "(ABC-\\d+)": "[`$1`](https://issues.apache.org/jira/browse/$1)"
    }
  }
}

Here, any time a pattern like ABC-123 appears in your log, it will be replaced with a link to the relevant issue in Jira. Each pattern is applied using string.replace(new RegExp(key, 'g'), value).

Handlebars setup file

The --handlebars-setup options allows you to point to a file to add custom Handlebars helpers, for use in custom templates using --template. Paths are relative to the directory in which you run auto-changelog. Because this file is loaded via require, it can only be passed on the command line; setting handlebarsSetup in in-repo config makes auto-changelog refuse to run (see Security).

auto-changelog --handlebars-setup setup.js --template custom-template.hbs

// setup.js
module.exports = function (Handlebars) {
  Handlebars.registerHelper('custom', function (context, options) {
    return 'custom helpers!'
  })
}

// custom-template.hbs
Now you can use {{custom}}

FAQ

What’s a changelog?

See keepachangelog.com.

What does this do?

The command