UNPKG

6.43 kBMarkdownView Raw
1# conventional-changelog-cli
2
3[![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][daviddm-image]][daviddm-url] [![Coverage percentage][coveralls-image]][coveralls-url]
4
5> Generate a changelog from git metadata
6
7*[Changelog?](https://speakerdeck.com/stevemao/compose-a-changelog)*
8
9**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.
10
11
12## Quick start
13
14```sh
15$ npm install -g conventional-changelog-cli
16$ cd my-project
17$ conventional-changelog -p angular -i CHANGELOG.md -s
18```
19
20This 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".
21
22If you first time use this tool and want to generate all previous changelog, you could do
23
24```sh
25$ conventional-changelog -p angular -i CHANGELOG.md -s -r 0
26```
27
28This *will* overwrite any previous changelog if exist.
29
30All available command line parameters can be listed using CLI: `conventional-changelog --help`.
31
32**Hint:** You can alias your command or add it to your package.json. EG: `"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"`.
33
34To fully customize the tool, please checkout [conventional-changelog](https://github.com/ajoslin/conventional-changelog) and [conventional-changelog-core](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/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.**
35
36
37## Example output
38
39- https://github.com/ajoslin/conventional-changelog/blob/master/CHANGELOG.md
40- https://github.com/karma-runner/karma/blob/master/CHANGELOG.md
41- https://github.com/btford/grunt-conventional-changelog/blob/master/CHANGELOG.md
42
43
44## Recommended workflow
45
461. Make changes
471. Commit those changes
481. Make sure Travis turns green
491. Bump version in `package.json`
501. `conventionalChangelog`
511. Commit `package.json` and `CHANGELOG.md` files
521. Tag
531. Push
54
55The 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.
56
57
58### With `npm version`
59
60Using the npm scripts to our advantage with the following hooks:
61
62```json
63{
64 "scripts": {
65 "version": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md"
66 }
67}
68```
69
70You could follow the following workflow
71
721. Make changes
731. Commit those changes
741. Pull all the tags
751. Run the [`npm version [path|minor|major]`](https://docs.npmjs.com/cli/version) command
761. Push
77
78You could optionally add a `preversion` script to package your project or running a full suit of test.
79And a `postversion` script to clean your system and push your release and tags.
80
81By adding a `.npmrc` you could also automate your commit message and set your tag prefix as such:
82
83```
84tag-version-prefix=""
85message="chore(release): %s :tada:"
86```
87
88
89## Why
90
91- Used by AngularJS, JSHint and related projects.
92- Easy fully automate changelog generation. You could still add more points on top of it.
93- Ignoring reverted commits, templating with [handlebars.js](https://github.com/wycats/handlebars.js) and links to references, etc. Open an [issue](../../issues/new) if you want more reasonable features.
94- Intelligently setup defaults but yet fully configurable with presets of [popular projects](https://github.com/ajoslin/conventional-changelog#preset).
95- Everything internally or externally is pluggable.
96- A lot of tests and actively maintained.
97
98### Problems with [github-changelog-generator](https://github.com/skywinder/github-changelog-generator) or similar projects
99
100- Opinionated on how to write commits, issues or PRs.
101- No or partially support reference links.
102- Not system agnostic. Only support GitHub.
103- No template support. The output is mostly certain format of markdown.
104- No presets of popular commit message conventions.
105- Not modularized. Over the years [modularization is proven to be the best practice](https://github.com/sindresorhus/ama/issues/10#issuecomment-117766328).
106- No tests or coverage is too low. Program might be buggy.
107- Do not read your project's environment.
108- No or few task runner or build tool integrations.
109
110
111## Related
112
113- [conventional-changelog](https://github.com/ajoslin/conventional-changelog) - API of this module
114- [standard-changelog](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/standard-changelog) - Similar to this module but only with angular convention
115- [conventional-github-releaser](https://github.com/conventional-changelog/conventional-github-releaser) - Make a new GitHub release from git metadata
116- [conventional-recommended-bump](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-recommended-bump) - Get a recommended version bump based on conventional commits
117- [conventional-commits-detector](https://github.com/conventional-changelog/conventional-commits-detector) - Detect what commit message convention your repository is using
118- [commitizen](https://github.com/commitizen/cz-cli) - Simple commit conventions for internet citizens.
119- [angular-precommit](https://github.com/ajoslin/angular-precommit) - Pre commit with angular conventions
120- [commitlint](https://github.com/marionebl/commitlint) - Lint commit messages
121
122
123## License
124
125MIT © [Steve Mao](https://github.com/stevemao)
126
127
128[npm-image]: https://badge.fury.io/js/conventional-changelog-cli.svg
129[npm-url]: https://npmjs.org/package/conventional-changelog-cli
130[travis-image]: https://travis-ci.org/conventional-changelog/conventional-changelog-cli.svg?branch=master
131[travis-url]: https://travis-ci.org/conventional-changelog/conventional-changelog-cli
132[daviddm-image]: https://david-dm.org/conventional-changelog/conventional-changelog-cli.svg?theme=shields.io
133[daviddm-url]: https://david-dm.org/conventional-changelog/conventional-changelog-cli
134[coveralls-image]: https://coveralls.io/repos/conventional-changelog/conventional-changelog-cli/badge.svg
135[coveralls-url]: https://coveralls.io/r/conventional-changelog/conventional-changelog-cli