commander 6.2.1 → 7.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +140 -105
- package/Readme.md +318 -195
- package/index.js +792 -473
- package/package.json +15 -12
- package/typings/index.d.ts +241 -30
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,132 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
|
|
|
8
8
|
<!-- markdownlint-disable MD024 -->
|
|
9
9
|
<!-- markdownlint-disable MD004 -->
|
|
10
10
|
|
|
11
|
+
## [7.0.0] (2021-01-15)
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- `.enablePositionalOptions()` to let program and subcommand reuse same option ([#1427])
|
|
16
|
+
- `.passThroughOptions()` to pass options through to other programs without needing `--` ([#1427])
|
|
17
|
+
- `.allowExcessArguments(false)` to show an error message if there are too many command-arguments on command line for the action handler ([#1409])
|
|
18
|
+
- `.configureOutput()` to modify use of stdout and stderr or customise display of errors ([#1387])
|
|
19
|
+
- use `.addHelpText()` to add text before or after the built-in help, for just current command or also for all subcommands ([#1296])
|
|
20
|
+
- enhance Option class ([#1331])
|
|
21
|
+
- allow hiding options from help
|
|
22
|
+
- allow restricting option arguments to a list of choices
|
|
23
|
+
- allow setting how default value is shown in help
|
|
24
|
+
- `.createOption()` to support subclassing of automatically created options (like `.createCommand()`) ([#1380])
|
|
25
|
+
- refactor the code generating the help into a separate public Help class ([#1365])
|
|
26
|
+
- support sorting subcommands and options in help
|
|
27
|
+
- support specifying wrap width (columns)
|
|
28
|
+
- allow subclassing Help class
|
|
29
|
+
- allow configuring Help class without subclassing
|
|
30
|
+
|
|
31
|
+
### Changed
|
|
32
|
+
|
|
33
|
+
- *Breaking:* options are stored safely by default, not as properties on the command ([#1409])
|
|
34
|
+
- this especially affects accessing options on program, use `program.opts()`
|
|
35
|
+
- revert behaviour with `.storeOptionsAsProperties()`
|
|
36
|
+
- *Breaking:* action handlers are passed options and command separately ([#1409])
|
|
37
|
+
- deprecated callback parameter to `.help()` and `.outputHelp()` (removed from README) ([#1296])
|
|
38
|
+
- *Breaking:* errors now displayed using `process.stderr.write()` instead of `console.error()`
|
|
39
|
+
- deprecate `.on('--help')` (removed from README) ([#1296])
|
|
40
|
+
- initialise the command description to empty string (previously undefined) ([#1365])
|
|
41
|
+
- document and annotate deprecated routines ([#1349])
|
|
42
|
+
|
|
43
|
+
### Fixed
|
|
44
|
+
|
|
45
|
+
- wrapping bugs in help ([#1365])
|
|
46
|
+
- first line of command description was wrapping two characters early
|
|
47
|
+
- pad width calculation was not including help option and help command
|
|
48
|
+
- pad width calculation was including hidden options and commands
|
|
49
|
+
- improve backwards compatibility for custom command event listeners ([#1403])
|
|
50
|
+
|
|
51
|
+
### Deleted
|
|
52
|
+
|
|
53
|
+
- *Breaking:* `.passCommandToAction()` ([#1409])
|
|
54
|
+
- no longer needed as action handler is passed options and command
|
|
55
|
+
- *Breaking:* "extra arguments" parameter to action handler ([#1409])
|
|
56
|
+
- if being used to detect excess arguments, there is now an error displayed by default
|
|
57
|
+
|
|
58
|
+
### Migration Tips
|
|
59
|
+
|
|
60
|
+
The biggest change is the parsed option values. Previously the options were stored by default as properties on the command object, and now the options are stored separately.
|
|
61
|
+
|
|
62
|
+
If you wish to restore the old behaviour and get running quickly you can call `.storeOptionsAsProperties()`.
|
|
63
|
+
To allow you to move to the new code patterns incrementally, the action handler will be passed the command _twice_,
|
|
64
|
+
to match the new "options" and "command" parameters (see below).
|
|
65
|
+
|
|
66
|
+
**program options**
|
|
67
|
+
|
|
68
|
+
Use the `.opts()` method to access the options. This is available on any command but is used most with the program.
|
|
69
|
+
|
|
70
|
+
```js
|
|
71
|
+
program.option('-d, --debug');
|
|
72
|
+
program.parse();
|
|
73
|
+
// Old code before Commander 7
|
|
74
|
+
if (program.debug) console.log(`Program name is ${program.name()}`);
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
```js
|
|
78
|
+
// New code
|
|
79
|
+
const options = program.opts();
|
|
80
|
+
if (options.debug) console.log(`Program name is ${program.name()}`);
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
**action handler**
|
|
84
|
+
|
|
85
|
+
The action handler gets passed a parameter for each command-argument you declared. Previously by default the next parameter was the command object with the options as properties. Now the next two parameters are instead the options and the command. If you
|
|
86
|
+
only accessed the options there may be no code changes required.
|
|
87
|
+
|
|
88
|
+
```js
|
|
89
|
+
program
|
|
90
|
+
.command('compress <filename>')
|
|
91
|
+
.option('-t, --trace')
|
|
92
|
+
// Old code before Commander 7
|
|
93
|
+
.action((filename, cmd)) => {
|
|
94
|
+
if (cmd.trace) console.log(`Command name is ${cmd.name()}`);
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
```js
|
|
99
|
+
// New code
|
|
100
|
+
.action((filename, options, command)) => {
|
|
101
|
+
if (options.trace) console.log(`Command name is ${command.name()}`);
|
|
102
|
+
});
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
If you already set `.storeOptionsAsProperties(false)` you may still need to adjust your code.
|
|
106
|
+
|
|
107
|
+
```js
|
|
108
|
+
program
|
|
109
|
+
.command('compress <filename>')
|
|
110
|
+
.storeOptionsAsProperties(false)
|
|
111
|
+
.option('-t, --trace')
|
|
112
|
+
// Old code before Commander 7
|
|
113
|
+
.action((filename, command)) => {
|
|
114
|
+
if (command.opts().trace) console.log(`Command name is ${command.name()}`);
|
|
115
|
+
});
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
```js
|
|
119
|
+
// New code
|
|
120
|
+
.action((filename, options, command)) => {
|
|
121
|
+
if (command.opts().trace) console.log(`Command name is ${command.name()}`);
|
|
122
|
+
});
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## [7.0.0-2] (2020-12-14)
|
|
126
|
+
|
|
127
|
+
(Released in 7.0.0)
|
|
128
|
+
|
|
129
|
+
## [7.0.0-1] (2020-11-21)
|
|
130
|
+
|
|
131
|
+
(Released in 7.0.0)
|
|
132
|
+
|
|
133
|
+
## [7.0.0-0] (2020-10-25)
|
|
134
|
+
|
|
135
|
+
(Released in 7.0.0)
|
|
136
|
+
|
|
11
137
|
## [6.2.1] (2020-12-13)
|
|
12
138
|
|
|
13
139
|
### Fixed
|
|
@@ -178,90 +304,9 @@ to expand `-fb` to `-f -b` rather than `-f b`.
|
|
|
178
304
|
|
|
179
305
|
(Released in 5.0.0)
|
|
180
306
|
|
|
181
|
-
## [4.1.1] (2020-02-02)
|
|
182
|
-
|
|
183
|
-
### Fixed
|
|
184
|
-
|
|
185
|
-
* TypeScript definition for `.action()` should include Promise for async ([#1157])
|
|
186
|
-
|
|
187
|
-
## [4.1.0] (2020-01-06)
|
|
188
|
-
|
|
189
|
-
### Added
|
|
190
|
-
|
|
191
|
-
* two routines to change how option values are handled, and eliminate name clashes with command properties ([#933] [#1102])
|
|
192
|
-
* see storeOptionsAsProperties and passCommandToAction in README
|
|
193
|
-
* `.parseAsync` to use instead of `.parse` if supply async action handlers ([#806] [#1118])
|
|
194
|
-
|
|
195
|
-
### Fixed
|
|
196
|
-
|
|
197
|
-
* Remove trailing blanks from wrapped help text ([#1096])
|
|
198
|
-
|
|
199
|
-
### Changed
|
|
200
|
-
|
|
201
|
-
* update dependencies
|
|
202
|
-
* extend security coverage for Commander 2.x to 2020-02-03
|
|
203
|
-
* improvements to README
|
|
204
|
-
* improvements to TypeScript definition documentation
|
|
205
|
-
* move old versions out of main CHANGELOG
|
|
206
|
-
* removed explicit use of `ts-node` in tests
|
|
207
|
-
|
|
208
|
-
## [4.0.1] (2019-11-12)
|
|
209
|
-
|
|
210
|
-
### Fixed
|
|
211
|
-
|
|
212
|
-
* display help when requested, even if there are missing required options ([#1091])
|
|
213
|
-
|
|
214
|
-
## [4.0.0] (2019-11-02)
|
|
215
|
-
|
|
216
|
-
### Added
|
|
217
|
-
|
|
218
|
-
* automatically wrap and indent help descriptions for options and commands ([#1051])
|
|
219
|
-
* `.exitOverride()` allows override of calls to `process.exit` for additional error handling and to keep program running ([#1040])
|
|
220
|
-
* support for declaring required options with `.requiredOptions()` ([#1071])
|
|
221
|
-
* GitHub Actions support ([#1027])
|
|
222
|
-
* translation links in README
|
|
223
|
-
|
|
224
|
-
### Changed
|
|
225
|
-
|
|
226
|
-
* dev: switch tests from Sinon+Should to Jest with major rewrite of tests ([#1035])
|
|
227
|
-
* call default subcommand even when there are unknown options ([#1047])
|
|
228
|
-
* *Breaking* Commander is only officially supported on Node 8 and above, and requires Node 6 ([#1053])
|
|
229
|
-
|
|
230
|
-
### Fixed
|
|
231
|
-
|
|
232
|
-
* *Breaking* keep command object out of program.args when action handler called ([#1048])
|
|
233
|
-
* also, action handler now passed array of unknown arguments
|
|
234
|
-
* complain about unknown options when program argument supplied and action handler ([#1049])
|
|
235
|
-
* this changes parameters to `command:*` event to include unknown arguments
|
|
236
|
-
* removed deprecated `customFds` option from call to `child_process.spawn` ([#1052])
|
|
237
|
-
* rework TypeScript declarations to bring all types into imported namespace ([#1081])
|
|
238
|
-
|
|
239
|
-
### Migration Tips
|
|
240
|
-
|
|
241
|
-
#### Testing for no arguments
|
|
242
|
-
|
|
243
|
-
If you were previously using code like:
|
|
244
|
-
|
|
245
|
-
```js
|
|
246
|
-
if (!program.args.length) ...
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
a partial replacement is:
|
|
250
|
-
|
|
251
|
-
```js
|
|
252
|
-
if (program.rawArgs.length < 3) ...
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
## [4.0.0-1] Prerelease (2019-10-08)
|
|
256
|
-
|
|
257
|
-
(Released in 4.0.0)
|
|
258
|
-
|
|
259
|
-
## [4.0.0-0] Prerelease (2019-10-01)
|
|
260
|
-
|
|
261
|
-
(Released in 4.0.0)
|
|
262
|
-
|
|
263
307
|
## Older versions
|
|
264
308
|
|
|
309
|
+
* [4.x](./changelogs/CHANGELOG-4.md)
|
|
265
310
|
* [3.x](./changelogs/CHANGELOG-3.md)
|
|
266
311
|
* [2.x](./changelogs/CHANGELOG-2.md)
|
|
267
312
|
* [1.x](./changelogs/CHANGELOG-1.md)
|
|
@@ -276,29 +321,13 @@ if (program.rawArgs.length < 3) ...
|
|
|
276
321
|
[#742]: https://github.com/tj/commander.js/issues/742
|
|
277
322
|
[#764]: https://github.com/tj/commander.js/issues/764
|
|
278
323
|
[#802]: https://github.com/tj/commander.js/issues/802
|
|
279
|
-
[#806]: https://github.com/tj/commander.js/issues/806
|
|
280
324
|
[#809]: https://github.com/tj/commander.js/issues/809
|
|
281
325
|
[#948]: https://github.com/tj/commander.js/issues/948
|
|
282
326
|
[#962]: https://github.com/tj/commander.js/issues/962
|
|
283
327
|
[#995]: https://github.com/tj/commander.js/issues/995
|
|
284
|
-
[#1027]: https://github.com/tj/commander.js/pull/1027
|
|
285
328
|
[#1032]: https://github.com/tj/commander.js/issues/1032
|
|
286
|
-
[#1035]: https://github.com/tj/commander.js/pull/1035
|
|
287
|
-
[#1040]: https://github.com/tj/commander.js/pull/1040
|
|
288
|
-
[#1047]: https://github.com/tj/commander.js/pull/1047
|
|
289
|
-
[#1048]: https://github.com/tj/commander.js/pull/1048
|
|
290
|
-
[#1049]: https://github.com/tj/commander.js/pull/1049
|
|
291
|
-
[#1051]: https://github.com/tj/commander.js/pull/1051
|
|
292
|
-
[#1052]: https://github.com/tj/commander.js/pull/1052
|
|
293
|
-
[#1053]: https://github.com/tj/commander.js/pull/1053
|
|
294
329
|
[#1062]: https://github.com/tj/commander.js/pull/1062
|
|
295
|
-
[#1071]: https://github.com/tj/commander.js/pull/1071
|
|
296
|
-
[#1081]: https://github.com/tj/commander.js/pull/1081
|
|
297
330
|
[#1088]: https://github.com/tj/commander.js/issues/1088
|
|
298
|
-
[#1091]: https://github.com/tj/commander.js/pull/1091
|
|
299
|
-
[#1096]: https://github.com/tj/commander.js/pull/1096
|
|
300
|
-
[#1102]: https://github.com/tj/commander.js/pull/1102
|
|
301
|
-
[#1118]: https://github.com/tj/commander.js/pull/1118
|
|
302
331
|
[#1119]: https://github.com/tj/commander.js/pull/1119
|
|
303
332
|
[#1133]: https://github.com/tj/commander.js/pull/1133
|
|
304
333
|
[#1138]: https://github.com/tj/commander.js/pull/1138
|
|
@@ -306,7 +335,6 @@ if (program.rawArgs.length < 3) ...
|
|
|
306
335
|
[#1146]: https://github.com/tj/commander.js/pull/1146
|
|
307
336
|
[#1149]: https://github.com/tj/commander.js/pull/1149
|
|
308
337
|
[#1153]: https://github.com/tj/commander.js/issues/1153
|
|
309
|
-
[#1157]: https://github.com/tj/commander.js/pull/1157
|
|
310
338
|
[#1159]: https://github.com/tj/commander.js/pull/1159
|
|
311
339
|
[#1165]: https://github.com/tj/commander.js/pull/1165
|
|
312
340
|
[#1169]: https://github.com/tj/commander.js/pull/1169
|
|
@@ -325,6 +353,7 @@ if (program.rawArgs.length < 3) ...
|
|
|
325
353
|
[#1250]: https://github.com/tj/commander.js/pull/1250
|
|
326
354
|
[#1256]: https://github.com/tj/commander.js/pull/1256
|
|
327
355
|
[#1275]: https://github.com/tj/commander.js/pull/1275
|
|
356
|
+
[#1296]: https://github.com/tj/commander.js/pull/1296
|
|
328
357
|
[#1301]: https://github.com/tj/commander.js/issues/1301
|
|
329
358
|
[#1306]: https://github.com/tj/commander.js/pull/1306
|
|
330
359
|
[#1312]: https://github.com/tj/commander.js/pull/1312
|
|
@@ -332,15 +361,27 @@ if (program.rawArgs.length < 3) ...
|
|
|
332
361
|
[#1323]: https://github.com/tj/commander.js/pull/1323
|
|
333
362
|
[#1325]: https://github.com/tj/commander.js/pull/1325
|
|
334
363
|
[#1326]: https://github.com/tj/commander.js/pull/1326
|
|
364
|
+
[#1331]: https://github.com/tj/commander.js/pull/1331
|
|
335
365
|
[#1332]: https://github.com/tj/commander.js/pull/1332
|
|
366
|
+
[#1349]: https://github.com/tj/commander.js/pull/1349
|
|
336
367
|
[#1353]: https://github.com/tj/commander.js/pull/1353
|
|
337
368
|
[#1360]: https://github.com/tj/commander.js/pull/1360
|
|
338
369
|
[#1361]: https://github.com/tj/commander.js/pull/1361
|
|
370
|
+
[#1365]: https://github.com/tj/commander.js/pull/1365
|
|
339
371
|
[#1368]: https://github.com/tj/commander.js/pull/1368
|
|
340
372
|
[#1375]: https://github.com/tj/commander.js/pull/1375
|
|
373
|
+
[#1380]: https://github.com/tj/commander.js/pull/1380
|
|
374
|
+
[#1387]: https://github.com/tj/commander.js/pull/1387
|
|
341
375
|
[#1390]: https://github.com/tj/commander.js/pull/1390
|
|
376
|
+
[#1403]: https://github.com/tj/commander.js/pull/1403
|
|
377
|
+
[#1409]: https://github.com/tj/commander.js/pull/1409
|
|
378
|
+
[#1427]: https://github.com/tj/commander.js/pull/1427
|
|
342
379
|
|
|
343
380
|
[Unreleased]: https://github.com/tj/commander.js/compare/master...develop
|
|
381
|
+
[7.0.0]: https://github.com/tj/commander.js/compare/v6.2.1...v7.0.0
|
|
382
|
+
[7.0.0-2]: https://github.com/tj/commander.js/compare/v7.0.0-1...v7.0.0-2
|
|
383
|
+
[7.0.0-1]: https://github.com/tj/commander.js/compare/v7.0.0-0...v7.0.0-1
|
|
384
|
+
[7.0.0-0]: https://github.com/tj/commander.js/compare/v6.2.0...v7.0.0-0
|
|
344
385
|
[6.2.1]: https://github.com/tj/commander.js/compare/v6.2.0..v6.2.1
|
|
345
386
|
[6.2.0]: https://github.com/tj/commander.js/compare/v6.1.0..v6.2.0
|
|
346
387
|
[6.1.0]: https://github.com/tj/commander.js/compare/v6.0.0..v6.1.0
|
|
@@ -353,9 +394,3 @@ if (program.rawArgs.length < 3) ...
|
|
|
353
394
|
[5.0.0-2]: https://github.com/tj/commander.js/compare/v5.0.0-1..v5.0.0-2
|
|
354
395
|
[5.0.0-1]: https://github.com/tj/commander.js/compare/v5.0.0-0..v5.0.0-1
|
|
355
396
|
[5.0.0-0]: https://github.com/tj/commander.js/compare/v4.1.1..v5.0.0-0
|
|
356
|
-
[4.1.1]: https://github.com/tj/commander.js/compare/v4.1.0..v4.1.1
|
|
357
|
-
[4.1.0]: https://github.com/tj/commander.js/compare/v4.0.1..v4.1.0
|
|
358
|
-
[4.0.1]: https://github.com/tj/commander.js/compare/v4.0.0..v4.0.1
|
|
359
|
-
[4.0.0]: https://github.com/tj/commander.js/compare/v3.0.2..v4.0.0
|
|
360
|
-
[4.0.0-1]: https://github.com/tj/commander.js/compare/v4.0.0-0..v4.0.0-1
|
|
361
|
-
[4.0.0-0]: https://github.com/tj/commander.js/compare/v3.0.2...v4.0.0-0
|