UNPKG

16.1 kBMarkdownView Raw
1# Changelog
2
3All notable changes to this project will be documented in this file.
4
5The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
6and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). (Format adopted after v3.0.0.)
7
8<!-- markdownlint-disable MD024 -->
9
10## [5.1.0] (2020-04-25)
11
12### Added
13
14- support for multiple command aliases, the first of which is shown in the auto-generated help ([#531], [#1236])
15- configuration support in `addCommand()` for `hidden` and `isDefault` ([#1232])
16
17### Fixed
18
19- omit masked help flags from the displayed help ([#645], [#1247])
20- remove old short help flag when change help flags using `helpOption` ([#1248])
21
22### Changed
23
24- remove use of `arguments` to improve auto-generated help in editors ([#1235])
25- rename `.command()` configuration `noHelp` to `hidden` (but not remove old support) ([#1232])
26- improvements to documentation
27- update dependencies
28- update tested versions of node
29- eliminate lint errors in TypeScript ([#1208])
30
31## [5.0.0] (2020-03-14)
32
33### Added
34
35* support for nested commands with action-handlers ([#1] [#764] [#1149])
36* `.addCommand()` for adding a separately configured command ([#764] [#1149])
37* allow a non-executable to be set as the default command ([#742] [#1149])
38* implicit help command when there are subcommands (previously only if executables) ([#1149])
39* customise implicit help command with `.addHelpCommand()` ([#1149])
40* display error message for unknown subcommand, by default ([#432] [#1088] [#1149])
41* display help for missing subcommand, by default ([#1088] [#1149])
42* combined short options as single argument may include boolean flags and value flag and value (e.g. `-a -b -p 80` can be written as `-abp80`) ([#1145])
43* `.parseOption()` includes short flag and long flag expansions ([#1145])
44* `.helpInformation()` returns help text as a string, previously a private routine ([#1169])
45* `.parse()` implicitly uses `process.argv` if arguments not specified ([#1172])
46* optionally specify where `.parse()` arguments "from", if not following node conventions ([#512] [#1172])
47* suggest help option along with unknown command error ([#1179])
48* TypeScript definition for `commands` property of `Command` ([#1184])
49* export `program` property ([#1195])
50* `createCommand` factory method to simplify subclassing ([#1191])
51
52### Fixed
53
54* preserve argument order in subcommands ([#508] [#962] [#1138])
55* do not emit `command:*` for executable subcommands ([#809] [#1149])
56* action handler called whether or not there are non-option arguments ([#1062] [#1149])
57* combining option short flag and value in single argument now works for subcommands ([#1145])
58* only add implicit help command when it will not conflict with other uses of argument ([#1153] [#1149])
59* implicit help command works with command aliases ([#948] [#1149])
60* options are validated whether or not there is an action handler ([#1149])
61
62### Changed
63
64* *Breaking* `.args` contains command arguments with just recognised options removed ([#1032] [#1138])
65* *Breaking* display error if required argument for command is missing ([#995] [#1149])
66* tighten TypeScript definition of custom option processing function passed to `.option()` ([#1119])
67* *Breaking* `.allowUnknownOption()` ([#802] [#1138])
68 * unknown options included in arguments passed to command action handler
69 * unknown options included in `.args`
70* only recognised option short flags and long flags are expanded (e.g. `-ab` or `--foo=bar`) ([#1145])
71* *Breaking* `.parseOptions()` ([#1138])
72 * `args` in returned result renamed `operands` and does not include anything after first unknown option
73 * `unknown` in returned result has arguments after first unknown option including operands, not just options and values
74* *Breaking* `.on('command:*', callback)` and other command events passed (changed) results from `.parseOptions`, i.e. operands and unknown ([#1138])
75* refactor Option from prototype to class ([#1133])
76* refactor Command from prototype to class ([#1159])
77* changes to error handling ([#1165])
78 * throw for author error, not just display message
79 * preflight for variadic error
80 * add tips to missing subcommand executable
81* TypeScript fluent return types changed to be more subclass friendly, return `this` rather than `Command` ([#1180])
82* `.parseAsync` returns `Promise<this>` to be consistent with `.parse()` ([#1180])
83* update dependencies
84
85### Removed
86
87* removed EventEmitter from TypeScript definition for Command, eliminating implicit peer dependency on `@types/node` ([#1146])
88* removed private function `normalize` (the functionality has been integrated into `parseOptions`) ([#1145])
89* `parseExpectedArgs` is now private ([#1149])
90
91### Migration Tips
92
93If you use `.on('command:*')` or more complicated tests to detect an unrecognised subcommand, you may be able to delete the code and rely on the default behaviour.
94
95If you use `program.args` or more complicated tests to detect a missing subcommand, you may be able to delete the code and rely on the default behaviour.
96
97If you use `.command('*')` to add a default command, you may be be able to switch to `isDefault:true` with a named command.
98
99## [5.0.0-4] (2020-03-03)
100
101(Released in 5.0.0)
102
103## [5.0.0-3] (2020-02-20)
104
105(Released in 5.0.0)
106
107## [5.0.0-2] (2020-02-10)
108
109(Released in 5.0.0)
110
111## [5.0.0-1] (2020-02-08)
112
113(Released in 5.0.0)
114
115## [5.0.0-0] (2020-02-02)
116
117(Released in 5.0.0)
118
119## [4.1.1] (2020-02-02)
120
121### Fixed
122
123* TypeScript definition for `.action()` should include Promise for async ([#1157])
124
125## [4.1.0] (2020-01-06)
126
127### Added
128
129* two routines to change how option values are handled, and eliminate name clashes with command properties ([#933] [#1102])
130 * see storeOptionsAsProperties and passCommandToAction in README
131* `.parseAsync` to use instead of `.parse` if supply async action handlers ([#806] [#1118])
132
133### Fixed
134
135* Remove trailing blanks from wrapped help text ([#1096])
136
137### Changed
138
139* update dependencies
140* extend security coverage for Commander 2.x to 2020-02-03
141* improvements to README
142* improvements to TypeScript definition documentation
143* move old versions out of main CHANGELOG
144* removed explicit use of `ts-node` in tests
145
146## [4.0.1] (2019-11-12)
147
148### Fixed
149
150* display help when requested, even if there are missing required options ([#1091])
151
152## [4.0.0] (2019-11-02)
153
154### Added
155
156* automatically wrap and indent help descriptions for options and commands ([#1051])
157* `.exitOverride()` allows override of calls to `process.exit` for additional error handling and to keep program running ([#1040])
158* support for declaring required options with `.requiredOptions()` ([#1071])
159* GitHub Actions support ([#1027])
160* translation links in README
161
162### Changed
163
164* dev: switch tests from Sinon+Should to Jest with major rewrite of tests ([#1035])
165* call default subcommand even when there are unknown options ([#1047])
166* *Breaking* Commander is only officially supported on Node 8 and above, and requires Node 6 ([#1053])
167
168### Fixed
169
170* *Breaking* keep command object out of program.args when action handler called ([#1048])
171 * also, action handler now passed array of unknown arguments
172* complain about unknown options when program argument supplied and action handler ([#1049])
173 * this changes parameters to `command:*` event to include unknown arguments
174* removed deprecated `customFds` option from call to `child_process.spawn` ([#1052])
175* rework TypeScript declarations to bring all types into imported namespace ([#1081])
176
177### Migration Tips
178
179#### Testing for no arguments
180
181If you were previously using code like:
182
183```js
184if (!program.args.length) ...
185```
186
187a partial replacement is:
188
189```js
190if (program.rawArgs.length < 3) ...
191```
192
193## [4.0.0-1] Prerelease (2019-10-08)
194
195(Released in 4.0.0)
196
197## [4.0.0-0] Prerelease (2019-10-01)
198
199(Released in 4.0.0)
200
201## [2.20.1] (2019-09-29)
202
203### Fixed
204
205* Improve tracking of executable subcommands.
206
207### Changed
208
209* update development dependencies
210
211## [3.0.2] (2019-09-27)
212
213### Fixed
214
215* Improve tracking of executable subcommands.
216
217### Changed
218
219* update development dependencies
220
221## [3.0.1] (2019-08-30)
222
223### Added
224
225* .name and .usage to README ([#1010])
226* Table of Contents to README ([#1010])
227* TypeScript definition for `executableFile` in CommandOptions ([#1028])
228
229### Changed
230
231* consistently use `const` rather than `var` in README ([#1026])
232
233### Fixed
234
235* help for sub commands with custom executableFile ([#1018])
236
237## [3.0.0] / 2019-08-08
238
239* Add option to specify executable file name ([#999])
240 * e.g. `.command('clone', 'clone description', { executableFile: 'myClone' })`
241* Change docs for `.command` to contrast action handler vs git-style executable. ([#938] [#990])
242* **Breaking** Change TypeScript to use overloaded function for `.command`. ([#938] [#990])
243* Change to use straight quotes around strings in error messages (like 'this' instead of `this') ([#915])
244* Add TypeScript "reference types" for node ([#974])
245* Add support for hyphen as an option argument in subcommands ([#697])
246* Add support for a short option flag and its value to be concatenated for action handler subcommands ([#599])
247 * e.g. `-p 80` can also be supplied as `-p80`
248* Add executable arguments to spawn in win32, for git-style executables ([#611])
249 * e.g. `node --harmony myCommand.js clone`
250* Add parent command as prefix of subcommand in help ([#980])
251* Add optional custom description to `.version` ([#963])
252 * e.g. `program.version('0.0.1', '-v, --vers', 'output the current version')`
253* Add `.helpOption(flags, description)` routine to customise help flags and description ([#963])
254 * e.g. `.helpOption('-e, --HELP', 'read more information')`
255* Fix behavior of --no-* options ([#795])
256 * can now define both `--foo` and `--no-foo`
257 * **Breaking** custom event listeners: `--no-foo` on cli now emits `option:no-foo` (previously `option:foo`)
258 * **Breaking** default value: defining `--no-foo` after defining `--foo` leaves the default value unchanged (previously set it to false)
259 * allow boolean default value, such as from environment ([#987])
260* Increment inspector port for spawned subcommands ([#991])
261 * e.g. `node --inspect myCommand.js clone`
262
263### Migration Tips
264
265The custom event for a negated option like `--no-foo` is `option:no-foo` (previously `option:foo`).
266
267```js
268program
269 .option('--no-foo')
270 .on('option:no-foo', () => {
271 console.log('removing foo');
272 });
273```
274
275When using TypeScript, adding a command does not allow an explicit `undefined` for an unwanted executable description (e.g
276for a command with an action handler).
277
278```js
279program
280 .command('action1', undefined, { noHelp: true }) // No longer valid
281 .command('action2', { noHelp: true }) // Correct
282```
283
284## 3.0.0-0 Prerelease / 2019-07-28
285
286(Released as 3.0.0)
287
288## Older versions
289
290* [2.x](./changelogs/CHANGELOG-2.md)
291* [1.x](./changelogs/CHANGELOG-1.md)
292* [0.x](./changelogs/CHANGELOG-0.md)
293
294[#1]: https://github.com/tj/commander.js/issues/1
295[#432]: https://github.com/tj/commander.js/issues/432
296[#508]: https://github.com/tj/commander.js/issues/508
297[#512]: https://github.com/tj/commander.js/issues/512
298[#531]: https://github.com/tj/commander.js/issues/531
299[#599]: https://github.com/tj/commander.js/issues/599
300[#611]: https://github.com/tj/commander.js/issues/611
301[#645]: https://github.com/tj/commander.js/issues/645
302[#697]: https://github.com/tj/commander.js/issues/697
303[#742]: https://github.com/tj/commander.js/issues/742
304[#764]: https://github.com/tj/commander.js/issues/764
305[#795]: https://github.com/tj/commander.js/issues/795
306[#802]: https://github.com/tj/commander.js/issues/802
307[#806]: https://github.com/tj/commander.js/issues/806
308[#809]: https://github.com/tj/commander.js/issues/809
309[#915]: https://github.com/tj/commander.js/issues/915
310[#938]: https://github.com/tj/commander.js/issues/938
311[#948]: https://github.com/tj/commander.js/issues/948
312[#962]: https://github.com/tj/commander.js/issues/962
313[#963]: https://github.com/tj/commander.js/issues/963
314[#974]: https://github.com/tj/commander.js/issues/974
315[#980]: https://github.com/tj/commander.js/issues/980
316[#987]: https://github.com/tj/commander.js/issues/987
317[#990]: https://github.com/tj/commander.js/issues/990
318[#991]: https://github.com/tj/commander.js/issues/991
319[#993]: https://github.com/tj/commander.js/issues/993
320[#995]: https://github.com/tj/commander.js/issues/995
321[#999]: https://github.com/tj/commander.js/issues/999
322[#1010]: https://github.com/tj/commander.js/pull/1010
323[#1018]: https://github.com/tj/commander.js/pull/1018
324[#1026]: https://github.com/tj/commander.js/pull/1026
325[#1027]: https://github.com/tj/commander.js/pull/1027
326[#1028]: https://github.com/tj/commander.js/pull/1028
327[#1032]: https://github.com/tj/commander.js/issues/1032
328[#1035]: https://github.com/tj/commander.js/pull/1035
329[#1040]: https://github.com/tj/commander.js/pull/1040
330[#1047]: https://github.com/tj/commander.js/pull/1047
331[#1048]: https://github.com/tj/commander.js/pull/1048
332[#1049]: https://github.com/tj/commander.js/pull/1049
333[#1051]: https://github.com/tj/commander.js/pull/1051
334[#1052]: https://github.com/tj/commander.js/pull/1052
335[#1053]: https://github.com/tj/commander.js/pull/1053
336[#1062]: https://github.com/tj/commander.js/pull/1062
337[#1071]: https://github.com/tj/commander.js/pull/1071
338[#1081]: https://github.com/tj/commander.js/pull/1081
339[#1088]: https://github.com/tj/commander.js/issues/1088
340[#1091]: https://github.com/tj/commander.js/pull/1091
341[#1096]: https://github.com/tj/commander.js/pull/1096
342[#1102]: https://github.com/tj/commander.js/pull/1102
343[#1118]: https://github.com/tj/commander.js/pull/1118
344[#1119]: https://github.com/tj/commander.js/pull/1119
345[#1133]: https://github.com/tj/commander.js/pull/1133
346[#1138]: https://github.com/tj/commander.js/pull/1138
347[#1145]: https://github.com/tj/commander.js/pull/1145
348[#1146]: https://github.com/tj/commander.js/pull/1146
349[#1149]: https://github.com/tj/commander.js/pull/1149
350[#1153]: https://github.com/tj/commander.js/issues/1153
351[#1157]: https://github.com/tj/commander.js/pull/1157
352[#1159]: https://github.com/tj/commander.js/pull/1159
353[#1165]: https://github.com/tj/commander.js/pull/1165
354[#1169]: https://github.com/tj/commander.js/pull/1169
355[#1172]: https://github.com/tj/commander.js/pull/1172
356[#1179]: https://github.com/tj/commander.js/pull/1179
357[#1180]: https://github.com/tj/commander.js/pull/1180
358[#1184]: https://github.com/tj/commander.js/pull/1184
359[#1191]: https://github.com/tj/commander.js/pull/1191
360[#1195]: https://github.com/tj/commander.js/pull/1195
361[#1208]: https://github.com/tj/commander.js/pull/1208
362[#1232]: https://github.com/tj/commander.js/pull/1232
363[#1235]: https://github.com/tj/commander.js/pull/1235
364[#1236]: https://github.com/tj/commander.js/pull/1236
365[#1247]: https://github.com/tj/commander.js/pull/1247
366[#1248]: https://github.com/tj/commander.js/pull/1248
367
368[Unreleased]: https://github.com/tj/commander.js/compare/master...develop
369[5.1.0]: https://github.com/tj/commander.js/compare/v5.0.0..v5.1.0
370[5.0.0]: https://github.com/tj/commander.js/compare/v4.1.1..v5.0.0
371[5.0.0-4]: https://github.com/tj/commander.js/compare/v5.0.0-3..v5.0.0-4
372[5.0.0-3]: https://github.com/tj/commander.js/compare/v5.0.0-2..v5.0.0-3
373[5.0.0-2]: https://github.com/tj/commander.js/compare/v5.0.0-1..v5.0.0-2
374[5.0.0-1]: https://github.com/tj/commander.js/compare/v5.0.0-0..v5.0.0-1
375[5.0.0-0]: https://github.com/tj/commander.js/compare/v4.1.1..v5.0.0-0
376[4.1.1]: https://github.com/tj/commander.js/compare/v4.1.0..v4.1.1
377[4.1.0]: https://github.com/tj/commander.js/compare/v4.0.1..v4.1.0
378[4.0.1]: https://github.com/tj/commander.js/compare/v4.0.0..v4.0.1
379[4.0.0]: https://github.com/tj/commander.js/compare/v3.0.2..v4.0.0
380[4.0.0-1]: https://github.com/tj/commander.js/compare/v4.0.0-0..v4.0.0-1
381[4.0.0-0]: https://github.com/tj/commander.js/compare/v3.0.2...v4.0.0-0
382[3.0.2]: https://github.com/tj/commander.js/compare/v3.0.1...v3.0.2
383[3.0.1]: https://github.com/tj/commander.js/compare/v3.0.0...v3.0.1
384[3.0.0]: https://github.com/tj/commander.js/compare/v2.20.1...v3.0.0
385[2.20.1]: https://github.com/tj/commander.js/compare/v2.20.0...v2.20.1