Skip to content
This repository has been archived by the owner on Feb 5, 2018. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Join the chat at

NPM version Build Status Dependency Status Coverage percentage

Generate a changelog from git metadata


Note You don't have to use the angular commit convention. For the best result of the tool to tokenize you commit and produce flexible output, it's recommended to use a commit convention.

Quick start

$ npm install -g conventional-changelog-cli
$ cd my-project
$ conventional-changelog -p angular -i -s

This will not overwrite any previous changelog. The above generates a changelog based on commits since the last semver tag that match the pattern of a "Feature", "Fix", "Performance Improvement" or "Breaking Changes".

If you first time use this tool and want to generate all previous changelog, you could do

$ conventional-changelog -p angular -i -s -r 0

This will overwrite any previous changelog if exist.

All available command line parameters can be listed using CLI: conventional-changelog --help.

Hint: You can alias your command or add it to your package.json. EG: "changelog": "conventional-changelog -p angular -i -s -r 0".

To fully customize the tool, please checkout conventional-changelog and conventional-changelog-core docs. You can find more details there. Note: config here can work with preset, which is different than options.config in conventional-changelog.

Example output

Recommended workflow

  1. Make changes
  2. Commit those changes
  3. Make sure Travis turns green
  4. Bump version in package.json
  5. conventionalChangelog
  6. Commit package.json and files
  7. Tag
  8. Push

The reason why you should commit and tag after conventionalChangelog is that the CHANGELOG should be included in the new release, hence gitRawCommitsOpts.from defaults to the latest semver tag.

If you use npm version, it auto tags immediately after changing the version in package.json. In such case, you might want to specify the version manually and generate the changelog before npm version.

Please use this gist to make a release or change it to your needs.


  • Used by AngularJS, JSHint and related projects.
  • Easy fully automate changelog generation. You could still add more points on top of it.
  • Ignoring reverted commits, templating with handlebars.js and links to references, etc. Open an issue if you want more reasonable features.
  • Intelligently setup defaults but yet fully configurable with presets of popular projects.
  • Everything internally or externally is pluggable.
  • A lot of tests and actively maintained.

Problems with github-changelog-generator or similar projects

  • Opinionated on how to write commits, issues or PRs.
  • No or partially support reference links.
  • Not system agnostic. Only support GitHub.
  • No template support. The output is mostly certain format of markdown.
  • No presets of popular commit message conventions.
  • Not modularized. Over the years modularization is proven to be the best practice.
  • No tests or coverage is too low. Program might be buggy.
  • Do not read your project's environment.
  • No or few task runner or build tool integrations.



MIT © Steve Mao