1 | # [![NPM version][npm-image]][npm-url] [![Build Status: Linux][travis-image]][travis-url] [![Build Status: Windows][appveyor-image]][appveyor-url] [![Dependency Status][daviddm-image]][daviddm-url] [![Coverage Status][coveralls-image]][coveralls-url]
|
2 |
|
3 | > [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) core
|
4 |
|
5 | You are probably looking for the [cli](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli) module. Or use one of the plugins if you are already using the tool: [grunt](https://github.com/btford/grunt-conventional-changelog)/[gulp](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/gulp-conventional-changelog)/[atom](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-atom).
|
6 |
|
7 | ## Usage
|
8 |
|
9 | ```sh
|
10 | $ npm install --save conventional-changelog-core
|
11 | ```
|
12 |
|
13 | ```js
|
14 | var conventionalChangelogCore = require('conventional-changelog-core');
|
15 |
|
16 | conventionalChangelogCore()
|
17 | .pipe(process.stdout); // or any writable stream
|
18 | ```
|
19 |
|
20 | ## API
|
21 |
|
22 | ### conventionalChangelogCore([options, [context, [gitRawCommitsOpts, [parserOpts, [writerOpts]]]]])
|
23 |
|
24 | Returns a readable stream.
|
25 |
|
26 | *Note:* [`options.transform`](#transform-1), [`options.pkg.transform`](#transform) and [`writerOpts.transform`](https://github.com/conventional-changelog/conventional-changelog-writer#transform) are different. If you have a better naming suggestion, please send a PR.
|
27 |
|
28 | #### options
|
29 |
|
30 | ##### config
|
31 |
|
32 | Type: `promise`, `function` or `object`
|
33 |
|
34 | This should serve as default values for other arguments of `conventionalChangelogCore` so you don't need to rewrite the same or similar config across your projects. Any value in this could be overwritten.
|
35 | If this is a promise (recommended if async), it should resolve with the config.
|
36 | If this is a function, it expects a node style callback with the config object.
|
37 | If this is an object, it is the config object. The config object should include `context`, `gitRawCommitsOpts`, `parserOpts` and `writerOpts`.
|
38 |
|
39 | ##### pkg
|
40 |
|
41 | Type: `object`
|
42 |
|
43 | ###### path
|
44 |
|
45 | Type: `string` Default: [closest package.json](https://github.com/sindresorhus/read-pkg-up).
|
46 |
|
47 | The location of your "package.json".
|
48 |
|
49 | ###### transform
|
50 |
|
51 | Type: `function` Default: pass through.
|
52 |
|
53 | 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.
|
54 |
|
55 | ##### append
|
56 |
|
57 | Type: `boolean` Default: `false`
|
58 |
|
59 | Should the log be appended to existing data.
|
60 |
|
61 | ##### releaseCount
|
62 |
|
63 | Type: `number` Default: `1`
|
64 |
|
65 | 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.
|
66 |
|
67 | ##### skipUnstable
|
68 |
|
69 | Type: `boolean` Default: `false`
|
70 |
|
71 | If set, unstable release tags will be skipped, e.g., x.x.x-rc.
|
72 |
|
73 | ##### debug
|
74 |
|
75 | Type: `function` Default: `function() {}`
|
76 |
|
77 | A debug function. EG: `console.debug.bind(console)`
|
78 |
|
79 | ##### warn
|
80 |
|
81 | Type: `function` Default: `options.debug`
|
82 |
|
83 | A warn function. EG: `grunt.verbose.writeln`
|
84 |
|
85 | ##### transform
|
86 |
|
87 | Type: `function` Default: get the version (without leading 'v') from tag and format date.
|
88 |
|
89 | ###### function(commit, cb)
|
90 |
|
91 | A transform function that applies after the parser and before the writer.
|
92 |
|
93 | This is the place to modify the parsed commits.
|
94 |
|
95 | ####### commit
|
96 |
|
97 | The commit from conventional-commits-parser.
|
98 |
|
99 | ####### cb
|
100 |
|
101 | Callback when you are done.
|
102 |
|
103 | ####### this
|
104 |
|
105 | `this` arg of through2.
|
106 |
|
107 | ##### outputUnreleased
|
108 |
|
109 | Type: `boolean` Default: `true` if a different version than last release is given. Otherwise `false`.
|
110 |
|
111 | If this value is `true` and `context.version` equals last release then `context.version` will be changed to `'Unreleased'`.
|
112 |
|
113 | **NOTE:** You may want to combine this option with `releaseCount` set to `0` to always overwrite the whole CHANGELOG. `conventional-changelog` only outputs a CHANGELOG but doesn't read any existing one.
|
114 |
|
115 | ##### lernaPackage
|
116 |
|
117 | Specify a package in lerna-style monorepo that the CHANGELOG should be generated for.
|
118 |
|
119 | Lerna tags releases in the format `foo-package@1.0.0` and assumes that packages
|
120 | are stored in the directory structure `./packages/foo-package`.
|
121 |
|
122 | ##### tagPrefix
|
123 |
|
124 | Specify a prefix for the git tag that will be taken into account during the comparison.
|
125 | For instance if your version tag is prefixed by `version/` instead of `v` you would specify `--tagPrefix=version/`
|
126 |
|
127 | #### context
|
128 |
|
129 | See the [conventional-changelog-writer](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer) docs. There are some defaults or changes:
|
130 |
|
131 | ##### host
|
132 |
|
133 | Default: normalized host found in `package.json`.
|
134 |
|
135 | ##### version
|
136 |
|
137 | Default: version found in `package.json`.
|
138 |
|
139 | ##### owner
|
140 |
|
141 | Default: extracted from normalized `package.json` `repository.url` field.
|
142 |
|
143 | ##### repository
|
144 |
|
145 | Default: extracted from normalized `package.json` `repository.url` field.
|
146 |
|
147 | ##### repoUrl
|
148 |
|
149 | Default: The whole normalized repository url in `package.json`.
|
150 |
|
151 | ##### gitSemverTags
|
152 |
|
153 | Type: `array`
|
154 |
|
155 | All git semver tags found in the repository. You can't overwrite this value.
|
156 |
|
157 | ##### previousTag
|
158 |
|
159 | Type: `string` Default: previous semver tag or the first commit hash if no previous tag.
|
160 |
|
161 | ##### currentTag
|
162 |
|
163 | Type: `string` Default: current semver tag or `'v'` + version if no current tag.
|
164 |
|
165 | ##### packageData
|
166 |
|
167 | Type: `object`
|
168 |
|
169 | Your `package.json` data. You can't overwrite this value.
|
170 |
|
171 | ##### linkCompare
|
172 |
|
173 | Type: `boolean` Default: `true` if `previousTag` and `currentTag` are truthy.
|
174 |
|
175 | Should link to the page that compares current tag with previous tag?
|
176 |
|
177 | #### gitRawCommitsOpts
|
178 |
|
179 | See the [git-raw-commits](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/git-raw-commits) docs. There are some defaults:
|
180 |
|
181 | ##### format
|
182 |
|
183 | Default: `'%B%n-hash-%n%H%n-gitTags-%n%d%n-committerDate-%n%ci'`
|
184 |
|
185 | ##### from
|
186 |
|
187 | Default: based on `options.releaseCount`.
|
188 |
|
189 | ##### reverse
|
190 |
|
191 | Default: `true` if `options.append` is truthy.
|
192 |
|
193 | ##### debug
|
194 |
|
195 | Type: `function` Default: `options.debug`
|
196 |
|
197 | #### parserOpts
|
198 |
|
199 | See the [conventional-commits-parser](https://github.com/conventional-changelog/conventional-commits-parser) docs.
|
200 |
|
201 | ##### warn
|
202 |
|
203 | Default: `options.warn`
|
204 |
|
205 | #### writerOpts
|
206 |
|
207 | See the [conventional-changelog-writer](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer) docs. There are some defaults:
|
208 |
|
209 | ##### finalizeContext
|
210 |
|
211 | Finalize context is used for generating above context.
|
212 |
|
213 | **NOTE:** If you overwrite this value the above context defaults will be gone.
|
214 |
|
215 | ##### debug
|
216 |
|
217 | Type: `function` Default: `options.debug`
|
218 |
|
219 | ##### reverse
|
220 |
|
221 | Default: `options.append`
|
222 |
|
223 | ##### doFlush
|
224 |
|
225 | Default: `options.outputUnreleased`
|
226 |
|
227 |
|
228 | ## Notes for parent modules
|
229 |
|
230 | This module has options `append` and `releaseCount`. However, it doesn't read your previous changelog. Reasons being:
|
231 |
|
232 | 1. 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.
|
233 | 2. 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.
|
234 | 3. We want the duty of this module to be very minimum.
|
235 |
|
236 | 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. Please see [conventional-github-releaser](https://github.com/conventional-changelog/conventional-github-releaser) as an example.
|
237 |
|
238 | Arguments passed to `conventionalChangelogCore` will be mutated.
|
239 |
|
240 |
|
241 | ## License
|
242 |
|
243 | MIT
|
244 |
|
245 |
|
246 | [npm-image]: https://badge.fury.io/js/conventional-changelog-core.svg
|
247 | [npm-url]: https://npmjs.org/package/conventional-changelog-core
|
248 | [travis-image]: https://travis-ci.org/conventional-changelog/conventional-changelog-core.svg?branch=master
|
249 | [travis-url]: https://travis-ci.org/conventional-changelog/conventional-changelog-core
|
250 | [appveyor-image]: https://ci.appveyor.com/api/projects/status/baoumm34w8c5o0hv/branch/master?svg=true
|
251 | [appveyor-url]: https://ci.appveyor.com/project/stevemao/conventional-changelog-core/branch/master
|
252 | [daviddm-image]: https://david-dm.org/conventional-changelog/conventional-changelog-core.svg?theme=shields.io
|
253 | [daviddm-url]: https://david-dm.org/conventional-changelog/conventional-changelog-core
|
254 | [coveralls-image]: https://coveralls.io/repos/conventional-changelog/conventional-changelog-core/badge.svg
|
255 | [coveralls-url]: https://coveralls.io/r/conventional-changelog/conventional-changelog-core
|