Generate a changelog from git metadata
Quick start
$ npm install -g conventional-changelog
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -w
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 CHANGELOG.md -w -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 CHANGELOG.md -w -r 0"
.
Or use one of the plugins if you are already using the tool: grunt/gulp/atom
Recommended workflow
- Make changes
- Commit those changes
- Make sure Travis turns green
- Bump version in
package.json
conventionalChangelog
- Commit
package.json
andCHANGELOG.md
files - Tag
- 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.
Please use this gist to make a release or change it to your needs.
Example output
- https://github.com/ajoslin/conventional-changelog/blob/master/CHANGELOG.md
- https://github.com/karma-runner/karma/blob/master/CHANGELOG.md
- https://github.com/btford/grunt-conventional-changelog/blob/master/CHANGELOG.md
Why
- Used by AngularJS and related projects.
- 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 you can still modify them to your needs.
- Fully configurable. There are many presets that you can use if you just want to use the same conventions. But it is also possible to configure if you want to go down to the nth degree.
- Everything internally or externally is pluggable.
- High performant. It doesn't spawn any extra child process to fetch data.
- A lot of tests and actively maintained.
Programmatic usage
$ npm install --save conventional-changelog
var conventionalChangelog = require('conventional-changelog');
conventionalChangelog({
preset: 'angular'
})
.pipe(process.stdout); // or any writable stream
API
conventionalChangelog([options, [context, [gitRawCommitsOpts, [parserOpts, [writerOpts]]]]])
Returns a readable stream.
options
preset
Type: string
Default values or any valid absolute or relative path
It's recommended to use a preset so you don't have to define everything yourself. The preset values can be overwritten.
pkg
Type: object
path
Type: string
Default: closest package.json.
The location of your "package.json".
transform
Type: function
Default: pass through.
A function that takes package.json
data as the argument and returns the modified data. Note this is performed before normalizing package.json data. Useful when you need to add a leading 'v' to your version or modify your repository url, etc.
append
Type: boolean
Default: false
Should the log be appended to existing data.
releaseCount
Type: number
Default: 1
How many releases of changelog you want to generate. It counts from the upcoming release. Useful when you forgot to generate any previous changelog. Set to 0
to regenerate all.
warn
Type: function
Default: function() {}
A warn function. EG: grunt.verbose.writeln
transform
Type: function
Default: get the version (without leading 'v') from tag and format date.
function(commit, cb)
A transform function that applies after the parser and before the writer.
This is the place to modify the parsed commits.
####### commit
The commit from conventional-commits-parser.
####### cb
Callback when you are done.
####### this
this
arg of through2.
context
See the conventional-changelog-writer docs. There are some defaults or changes:
host
Default: normalized host found in package.json
.
version
Default: version found in package.json
.
owner
Default: extracted from normalized package.json
repository.url
field.
repository
Default: extracted from normalized package.json
repository.url
field.
gitSemverTags
Type: array
All git semver tags found in the repository. You can't overwrite this value.
previousTag
Type: string
Default: previous tag or the first commit hash if no previous tag.
currentTag
Type: string
Default: current tag or 'v'
+ version if no current tag.
packageData
Type: object
Your package.json
data. You can't overwrite this value.
linkCompare
Type: boolean
Default: true
if previousTag
and currentTag
are truthy.
Should link to the page that compares current tag with previous tag?
gitRawCommitsOpts
See the git-raw-commits docs. There are some defaults:
format
Default: '%B%n-hash-%n%H%n-gitTags-%n%d%n-committerDate-%n%ci'
from
Default: based on options.releaseCount
.
reverse
Default: only true
if options.append
is truthy.
parserOpts
See the conventional-commits-parser docs.
writerOpts
See the conventional-changelog-writer docs. There are some defaults:
reverse
Default: same as options.append
.
CLI
$ npm install --global conventional-changelog
$ conventional-changelog --help # for more details
Notes for parent modules
This module has options append
and releaseCount
. However, it doesn't read your previous changelog. Reasons being:
- The old logs is just to be appended or prepended to the newly generated logs, which is a very simple thing that could be done in the parent module.
- We want it to be very flexible for the parent module. You could create a readable stream from the file or you could just read the file.
- We want the duty of this module to be very minimum.
So, when you build a parent module, you need to read the old logs and append or prepend to them based on options.append
. However, if options.releaseCount
is 0
you need to ignore any previous logs.
Related
- conventional-github-releaser - Make a new GitHub release from git metadata
- conventional-recommended-bump - Get a recommended version bump based on conventional commits
- conventional-commits-detector - Detect what commit message convention your repository is using
- commitizen - Simple commit conventions for internet citizens.
License
MIT