Install

``
npm install changelog-parser
`

Usage

This module exports a single function. It supports both callbacks and promises.

`js
var parseChangelog = require('changelog-parser')
`

$3

If provided with a callback, parseChangelog will invoke the function with the parsed changelog.

`js
parseChangelog('path/to/CHANGELOG.md', function (err, result) {
if (err) throw err

// changelog object
console.log(result)
})
`

$3

If no callback is provided, parseChangelog will return a Promise.

`js
parseChangelog('path/to/CHANGELOG.md')
.then(function (result) {
// changelog object
console.log(result)
})
.catch(function (err) {
// Whoops, something went wrong!
console.error(err)
})
`

$3

You can optionally provide a configuration object parseChangelog function.

You must provide either filePath or text.

#### filePath

Path to changelog file.

`js
parseChangelog({
filePath: 'path/to/CHANGELOG.md'
})
`

#### text

Text of changelog file (you can use this instead of filePath).

`js
parseChangelog({
text: 'raw changelog text in string format'
})
`

#### removeMarkdown

Removes the markdown markup from the changelog entries by default. You can change its value to false to keep the markdown.

`js
parseChangelog({
filePath: 'path/to/CHANGELOG.md',
removeMarkdown: false // default: true
})
`

$3

There is also a command-line interface available if you install it with -g.

`
npm install -g changelog-parser
`

This installs a program called changelog-parser that you simply pass a CHANGELOG.md file.

`
changelog-parser path/to/CHANGELOG.md
`

This will print the JSON object representing the change log to the terminal.

Alternately you can run it without arguments and it will look for a CHANGELOG.md file in the working directory.

Standards

This module assumes your change log is a markdown file structured roughly like so:

`markdown


changelog title

A cool description (optional).

unreleased

[a.b.c]: http://altavista.com
`

Parsing the above example will return the following object:

`js
{
title: 'changelog title',
description: 'A cool description (optional).',
versions: [
{ version: null,
title: 'unreleased',
date: null,
body: '* foo',
parsed: {
_: [
'foo'
]
}
},
{ version: 'x.y.z',
title: 'x.y.z - YYYY-MM-DD',
date: null,
body: '* bar',
parsed: {
_: [
'bar'
]
}
},
{ version: 'a.b.c',
title: '[a.b.c]',
date: null,
body: '### Changes\n\n Update API\n Fix bug #1',
parsed: {
_: [
'Update API',
'Fix bug #1'
],
Changes: [
'Update API',
'Fix bug #1'
]
}
},
{ version: '2.2.3-pre.1',
title: '2.2.3-pre.1 - 2013-02-14',
date: '2013-02-14',
body: '* Update API',
parsed: {
_: [
'Update API'
]
}
},
{ version: '2.0.0-x.7.z.92',
title: '2.0.0-x.7.z.92 - 2013-02-14',
date: '2013-02-14',
body: ' bark bark\n woof\n* arf',
parsed: {
_: [
'bark bark',
'woof',
'arf'
]
}
},
{ version: '1.3.0',
title: 'v1.3.0',
date: null,
body: '* make it so',
parsed: {
_: [
'make it so'
]
}
},
{ version: '1.2.3',
title: '1.2.3',
date: null,
body: '* init',
parsed: {
_: [
'init'
]
}
}
]
}
`

Expects versions to be semver compliant, otherwise sets version to null.

Each entry is available as an object in the versions array. The body of a given entry can be accessed using the following properties:

- body - A string containing all of the updates/changes/etc. for the current entry. This property includes both plain text and markdown.
- parsed - An object which points to one or more arrays of data for the current entry. All data for the current entry is present in the array at key _ (eg. parsed._). If the entry contains subheadings (eg. ### Added, ### Changed), then any items underneath each subheading will be present in an array at the corresponding key (eg. parsed.Added, parsed.Changed). Each array contains plain text.

CHANGELOG.md` standards are inspired by keepachangelog.com.

Contributing

Contributions welcome! Please read the contributing guidelines first.

See Also

- changelog-init
- gh-release

License

ISC

Log image is from emojipedia.