auto-changelog

Install the auto-changelog CLI tool globally via npm to use it in any git repository.

npm install -g auto-changelog

You can provide a custom .hbs template file via the --template flag. To see the data structure available to your template, generate a JSON version of the changelog using --template json.

Example template usage:

{{#each releases}}
  ### [{{title}}]({{href}})
  {{#each commits}}
    - {{subject}} [`{{shorthash}}`]({{href}})
  {{/each}}
{{/each}}

auto-changelog --template changelog-template.hbs

You can automate changelog generation by adding auto-changelog -p to your package.json version scripts. Using the -p (or --package) flag tells the tool to use the version from package.json as the latest release, ensuring that all commits since the last tag are included in the current version's section.

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

If you use a non-standard remote (like Redmine or a custom diff tool), you can override the automatically generated links using tokens {id} for single identifiers or {from} and {to} for version comparisons.

• --commit-url [url]: Use {id} for commit IDs.
• --issue-url [url]: Use {id} for issue IDs.
• --merge-url [url]: Use {id} for merge IDs.
• --compare-url [url]: Use {from} and {to} for tag comparisons.

# 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}

The tool automatically detects the Git provider from your remote URL and generates appropriate links. Supported providers include:

• Bitbucket: Uses /commits/{id}, /issues/{id}, /pull-requests/{id}, and /compare/{to}..{from}.
• GitLab: Uses /commit/{id}, /issues/{id}, /merge_requests/{id}, and /compare/{from}...{to}.
• Azure DevOps / Visual Studio: Uses /commit/{id}, /_workitems/edit/{id}, /pullrequest/{id}, and a specific branch comparison URL.
• GitHub (Default): For other providers (like GitHub), it defaults to /commit/{id}, /issues/{id}, /pull/{id}, and /compare/{from}...{to}.

You can define configuration options in two ways:

1. package.json: Use the auto-changelog key with camelCase option names. This takes precedence over other config files.
2. .auto-changelog file: A JSON file in your project root.

Example package.json configuration:

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

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

Use the replaceText option in your package.json to perform regex-based text replacement in the generated log. This is useful for turning issue IDs into clickable links.

Each pattern is applied using string.replace(new RegExp(key, 'g'), value).

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

Use the --handlebars-setup flag to point to a JavaScript file that registers custom Handlebars helpers for your templates.

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!'
  })
}

You can override the default link generation for commits, issues, merge requests, and comparisons by providing custom URL templates in your configuration. Use the following placeholder tokens within your URL strings:

• {id}: Replaced by the commit, issue, or merge request ID.
• {from}: Replaced by the starting version/tag/branch.
• {to}: Replaced by the ending version/tag/branch.

Supported override keys are commitUrl, issueUrl, mergeUrl, and compareUrl.