1 | # simple-commit-message
|
2 |
|
3 | > Simple commit message wizard and validator;
|
4 | > works with commitizen and pre-git
|
5 |
|
6 | [![NPM][simple-commit-message-icon] ][simple-commit-message-url]
|
7 |
|
8 | [![Build status][simple-commit-message-ci-image] ][simple-commit-message-ci-url]
|
9 | [![dependencies][simple-commit-message-dependencies-image] ][simple-commit-message-dependencies-url]
|
10 | [![devdependencies][simple-commit-message-devdependencies-image] ][simple-commit-message-devdependencies-url]
|
11 | [![semantic-release][semantic-image] ][semantic-url]
|
12 | [![manpm](https://img.shields.io/badge/manpm-%E2%9C%93-3399ff.svg)](https://github.com/bahmutov/manpm)
|
13 | [![standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)
|
14 |
|
15 | ## Purpose
|
16 |
|
17 | This module can:
|
18 |
|
19 | * parse simple commit message of the type `type(scope): message`
|
20 | * validate a given message if it fits the above simple format
|
21 | * guide the user with questions in order to form well formatted message
|
22 |
|
23 | ## Valid commit messages
|
24 |
|
25 | ### Simplest
|
26 |
|
27 | ```
|
28 | major: breaking change in API
|
29 | minor: this is a new feature
|
30 | fix: an example fix message
|
31 | ```
|
32 |
|
33 | ### Synonyms
|
34 |
|
35 | For convenience you can use synonyms:
|
36 |
|
37 | * "break: ..." is synonym to "major: ..."
|
38 | * "feat: ..." is synonym to "minor: ..."
|
39 | * "patch: ..." is synonym to "fix: ..."
|
40 |
|
41 | ### Scopes
|
42 |
|
43 | You can optionally put a *scope* for the commit. For example if you added
|
44 | a new feature to the `log` feature of the module
|
45 |
|
46 | ```
|
47 | feat(log): added colors!
|
48 | ```
|
49 |
|
50 | Similarly, you can add scope to each type
|
51 |
|
52 | ```
|
53 | major(scope): breaking change in API
|
54 | minor(something): this is a new feature
|
55 | fix(login): an example fix message
|
56 | ```
|
57 |
|
58 | ### Skip release
|
59 |
|
60 | If you just want to commit code, but not publish a new version from CI, you
|
61 | have several choices.
|
62 |
|
63 | ```
|
64 | chore(tests): writing more tests
|
65 | WIP: work in progress, not ready yet
|
66 | ```
|
67 |
|
68 | **note** if you have local commit message validation as a Git hook, for
|
69 | example using [pre-git](https://github.com/bahmutov/pre-git#readme)
|
70 | skip the message check using `git commit -n` option.
|
71 |
|
72 | ### Comments
|
73 |
|
74 | The commit message can have lines that start with `#` character. These
|
75 | lines will be ignored.
|
76 |
|
77 | ## Install and use
|
78 |
|
79 | npm install --save simple-commit-message
|
80 |
|
81 | Then use the following methods
|
82 |
|
83 | ```js
|
84 | var simple = require('simple-commit-message')
|
85 | simple.name // "simple"
|
86 | // returns an object with parsed info
|
87 | const result = simple.parse(message)
|
88 | /*
|
89 | {
|
90 | firstLine, // first message line
|
91 | type, // "major", "feat", "fix", "chore" or undefined
|
92 | scope, // inside of round braces
|
93 | subject // message after :
|
94 | */
|
95 | // returns true / false, prints errors to given log function or console.error
|
96 | simple.validate(message, log)
|
97 | // message wizard built on top of inquirer
|
98 | simple.prompter(inquirer, cb)
|
99 | // returns true if the commit message is public ("feat", etc)
|
100 | simple.isPublic(
|
101 | simple.parse("feat(foo): add foo feature").type
|
102 | ) // true
|
103 | ```
|
104 |
|
105 | See [inquirer](https://www.npmjs.com/package/inquirer) for details.
|
106 |
|
107 | ## As plugin for semantic-release
|
108 |
|
109 | This module can function as [analyzeCommits plugin](https://github.com/semantic-release/semantic-release#analyzecommits)
|
110 | for [semantic-release](https://github.com/semantic-release/semantic-release).
|
111 | Just add to the `package.json` (during install this will be done automatically)
|
112 |
|
113 | ```json
|
114 | {
|
115 | "release": {
|
116 | "analyzeCommits": "simple-commit-message"
|
117 | }
|
118 | }
|
119 | ```
|
120 |
|
121 | ### Versions
|
122 |
|
123 | * `1 ... 3.x` compatible with `semantic-release` v8
|
124 | * `4` compatible with `semantic-release` v11
|
125 |
|
126 | ## Wizard
|
127 |
|
128 | This module comes with included "bin" script that runs the wizard and asks you the questions.
|
129 | To use, add a script to your package, for example name it "commit"
|
130 |
|
131 | ```json
|
132 | {
|
133 | "scripts": {
|
134 | "commit": "simple-commit-message"
|
135 | }
|
136 | }
|
137 | ```
|
138 |
|
139 | Then instead of `git commit` use the command `npm run commit` and answer questions.
|
140 |
|
141 | ## Related
|
142 |
|
143 | * [conventional-commit-message](https://github.com/bahmutov/conventional-commit-message)
|
144 | is based on AngularJS log standard and has more commit types allowed.
|
145 |
|
146 | ## Debugging
|
147 |
|
148 | To see the commit processing logic locally, run
|
149 |
|
150 | ```sh
|
151 | GH_TOKEN=aaa NPM_TOKEN=fff $(npm bin)/semantic-release pre || true && git checkout .npmrc
|
152 | ```
|
153 |
|
154 | This will trigger local commit analysis without publishing.
|
155 |
|
156 | To see debug log messages run this plugin with `DEBUG=simple` environment
|
157 | variable.
|
158 |
|
159 | ### Small print
|
160 |
|
161 | Author: Gleb Bahmutov © 2015
|
162 |
|
163 | * [@bahmutov](https://twitter.com/bahmutov)
|
164 | * [glebbahmutov.com](http://glebbahmutov.com)
|
165 | * [blog](http://glebbahmutov.com/blog/)
|
166 |
|
167 | License: MIT - do anything with the code, but don't blame me if it does not work.
|
168 |
|
169 | Spread the word: tweet, star on github, etc.
|
170 |
|
171 | Support: if you find any problems with this module, email / tweet /
|
172 | [open issue](https://github.com/bahmutov/simple-commit-message/issues) on Github
|
173 |
|
174 | ## MIT License
|
175 |
|
176 | Copyright (c) 2015 Gleb Bahmutov
|
177 |
|
178 | Permission is hereby granted, free of charge, to any person
|
179 | obtaining a copy of this software and associated documentation
|
180 | files (the "Software"), to deal in the Software without
|
181 | restriction, including without limitation the rights to use,
|
182 | copy, modify, merge, publish, distribute, sublicense, and/or sell
|
183 | copies of the Software, and to permit persons to whom the
|
184 | Software is furnished to do so, subject to the following
|
185 | conditions:
|
186 |
|
187 | The above copyright notice and this permission notice shall be
|
188 | included in all copies or substantial portions of the Software.
|
189 |
|
190 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
191 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
|
192 | OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
193 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
|
194 | HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
195 | WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
196 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
197 | OTHER DEALINGS IN THE SOFTWARE.
|
198 |
|
199 | [simple-commit-message-icon]: https://nodei.co/npm/simple-commit-message.svg?downloads=true
|
200 | [simple-commit-message-url]: https://npmjs.org/package/simple-commit-message
|
201 | [simple-commit-message-ci-image]: https://travis-ci.org/bahmutov/simple-commit-message.svg?branch=master
|
202 | [simple-commit-message-ci-url]: https://travis-ci.org/bahmutov/simple-commit-message
|
203 | [simple-commit-message-dependencies-image]: https://david-dm.org/bahmutov/simple-commit-message.svg
|
204 | [simple-commit-message-dependencies-url]: https://david-dm.org/bahmutov/simple-commit-message
|
205 | [simple-commit-message-devdependencies-image]: https://david-dm.org/bahmutov/simple-commit-message/dev-status.svg
|
206 | [simple-commit-message-devdependencies-url]: https://david-dm.org/bahmutov/simple-commit-message#info=devDependencies
|
207 | [semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
|
208 | [semantic-url]: https://github.com/semantic-release/semantic-release
|