Skip to content

Commit e3192a1

Browse files
shadowspawnshadowspawn
authored
Merge pull request #2140 from tj/release/12.x
2 parents b0f789f + 608eaf0 commit e3192a1

31 files changed

+1405
-858
lines changed

‎.github/workflows/tests.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ jobs:
1212
strategy:
1313
fail-fast: false
1414
matrix:
15-
node-version: [16.x, 18.x, 20.x]
15+
node-version: [18.x, 20.x]
1616
os: [ubuntu-latest, windows-latest, macos-latest]
1717

1818
steps:

‎CHANGELOG.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,63 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
88
<!-- markdownlint-disable MD024 -->
99
<!-- markdownlint-disable MD004 -->
1010

11+
## [12.0.0] (2024-02-03)
12+
13+
### Added
14+
15+
- `.addHelpOption()` as another way of configuring built-in help option ([#2006])
16+
- `.helpCommand()` for configuring built-in help command ([#2087])
17+
18+
### Fixed
19+
20+
- *Breaking:* use non-zero exit code when spawned executable subcommand terminates due to a signal ([#2023])
21+
- *Breaking:* check `passThroughOptions` constraints when using `.addCommand` and throw if parent command does not have `.enablePositionalOptions()` enabled ([#1937])
22+
23+
### Changed
24+
25+
- *Breaking:* Commander 12 requires Node.js v18 or higher ([#2027])
26+
- *Breaking:* throw an error if add an option with a flag which is already in use ([#2055])
27+
- *Breaking:* throw an error if add a command with name or alias which is already in use ([#2059])
28+
- *Breaking:* throw error when calling `.storeOptionsAsProperties()` after setting an option value ([#1928])
29+
- replace non-standard JSDoc of `@api private` with documented `@private` ([#1949])
30+
- `.addHelpCommand()` now takes a Command (passing string or boolean still works as before but deprecated) ([#2087])
31+
- refactor internal implementation of built-in help option ([#2006])
32+
- refactor internal implementation of built-in help command ([#2087])
33+
34+
### Deprecated
35+
36+
- `.addHelpCommand()` passing string or boolean (use `.helpCommand()` or pass a Command) ([#2087])
37+
38+
### Removed
39+
40+
- *Breaking:* removed default export of a global Command instance from CommonJS (use the named `program` export instead) ([#2017])
41+
42+
### Migration Tips
43+
44+
**global program**
45+
46+
If you are using the [deprecated](./docs/deprecated.md#default-import-of-global-command-object) default import of the global Command object, you need to switch to using a named import (or create a new `Command`).
47+
48+
```js
49+
// const program = require('commander');
50+
const { program } = require('commander');
51+
```
52+
53+
**option and command clashes**
54+
55+
A couple of configuration problems now throw an error, which will pick up issues in existing programs:
56+
57+
- adding an option which uses the same flag as a previous option
58+
- adding a command which uses the same name or alias as a previous command
59+
60+
## [12.0.0-1] (2024-01-20)
61+
62+
(Released in 12.0.0)
63+
64+
## [12.0.0-0] (2023-11-11)
65+
66+
(Released in 12.0.0)
67+
1168
## [11.1.0] (2023-10-13)
1269

1370
### Fixed
@@ -1188,13 +1245,23 @@ program
11881245
[#1874]: https://github.com/tj/commander.js/pull/1874
11891246
[#1886]: https://github.com/tj/commander.js/pull/1886
11901247
[#1896]: https://github.com/tj/commander.js/pull/1896
1248+
[#1928]: https://github.com/tj/commander.js/pull/1928
11911249
[#1930]: https://github.com/tj/commander.js/pull/1930
1250+
[#1937]: https://github.com/tj/commander.js/pull/1937
1251+
[#1949]: https://github.com/tj/commander.js/pull/1949
11921252
[#1965]: https://github.com/tj/commander.js/pull/1965
11931253
[#1969]: https://github.com/tj/commander.js/pull/1969
11941254
[#1982]: https://github.com/tj/commander.js/pull/1982
11951255
[#1983]: https://github.com/tj/commander.js/pull/1983
1256+
[#2006]: https://github.com/tj/commander.js/pull/2006
11961257
[#2010]: https://github.com/tj/commander.js/pull/2010
1258+
[#2017]: https://github.com/tj/commander.js/pull/2017
11971259
[#2019]: https://github.com/tj/commander.js/pull/2019
1260+
[#2023]: https://github.com/tj/commander.js/pull/2023
1261+
[#2027]: https://github.com/tj/commander.js/pull/2027
1262+
[#2055]: https://github.com/tj/commander.js/pull/2055
1263+
[#2059]: https://github.com/tj/commander.js/pull/2059
1264+
[#2087]: https://github.com/tj/commander.js/pull/2087
11981265

11991266
<!-- Referenced in 5.x -->
12001267
[#1]: https://github.com/tj/commander.js/issues/1
@@ -1274,6 +1341,9 @@ program
12741341
[#1028]: https://github.com/tj/commander.js/pull/1028
12751342

12761343
[Unreleased]: https://github.com/tj/commander.js/compare/master...develop
1344+
[12.0.0]: https://github.com/tj/commander.js/compare/v11.1.0...v12.0.0
1345+
[12.0.0-1]: https://github.com/tj/commander.js/compare/v12.0.0-0...v12.0.0-1
1346+
[12.0.0-0]: https://github.com/tj/commander.js/compare/v11.1.0...v12.0.0-0
12771347
[11.1.0]: https://github.com/tj/commander.js/compare/v11.0.0...v11.1.0
12781348
[11.0.0]: https://github.com/tj/commander.js/compare/v10.0.1...v11.0.0
12791349
[10.0.1]: https://github.com/tj/commander.js/compare/v10.0.0...v10.0.1

‎Readme.md

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
3737
- [.usage](#usage)
3838
- [.description and .summary](#description-and-summary)
3939
- [.helpOption(flags, description)](#helpoptionflags-description)
40-
- [.addHelpCommand()](#addhelpcommand)
40+
- [.helpCommand()](#helpcommand)
4141
- [More configuration](#more-configuration-2)
4242
- [Custom event listeners](#custom-event-listeners)
4343
- [Bits and pieces](#bits-and-pieces)
@@ -904,16 +904,20 @@ program
904904
.helpOption('-e, --HELP', 'read more information');
905905
```
906906

907-
### .addHelpCommand()
907+
(Or use `.addHelpOption()` to add an option you construct yourself.)
908908

909-
A help command is added by default if your command has subcommands. You can explicitly turn on or off the implicit help command with `.addHelpCommand()` and `.addHelpCommand(false)`.
909+
### .helpCommand()
910+
911+
A help command is added by default if your command has subcommands. You can explicitly turn on or off the implicit help command with `.helpCommand(true)` and `.helpCommand(false)`.
910912

911913
You can both turn on and customise the help command by supplying the name and description:
912914

913915
```js
914-
program.addHelpCommand('assist [command]', 'show assistance');
916+
program.helpCommand('assist [command]', 'show assistance');
915917
```
916918

919+
(Or use `.addHelpCommand()` to add a command you construct yourself.)
920+
917921
### More configuration
918922

919923
The built-in help is formatted using the Help class.
@@ -1139,7 +1143,7 @@ There is more information available about:
11391143

11401144
## Support
11411145

1142-
The current version of Commander is fully supported on Long Term Support versions of Node.js, and requires at least v16.
1146+
The current version of Commander is fully supported on Long Term Support versions of Node.js, and requires at least v18.
11431147
(For older versions of Node.js, use an older version of Commander.)
11441148

11451149
The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.

‎Readme_zh-CN.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1059,7 +1059,7 @@ program
10591059
10601060
## 支持
10611061
1062-
当前版本的 Commander 在 LTS 版本的 Node.js 上完全支持。并且至少需要 v16。
1062+
当前版本的 Commander 在 LTS 版本的 Node.js 上完全支持。并且至少需要 v18。
10631063
（使用更低版本 Node.js 的用户建议安装更低版本的 Commander）
10641064
10651065
社区支持请访问项目的 [Issues](https://github.com/tj/commander.js/issues)。

‎SECURITY.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ Old versions receive security updates for six months.
66

77
| Version | Supported |
88
| ------- | ------------------------------------------ |
9-
| 10.x | :white_check_mark: support ends 2024-01-16 |
10-
| < 10 | :x: |
9+
| 11.x | :white_check_mark: support ends 2024-07-03 |
10+
| < 11 | :x: |
1111

1212
Pull Requests for security issues will be considered for older versions back to 2.x.
1313

‎docs/deprecated.md

Lines changed: 71 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,22 @@ These features are deprecated, which means they may go away in a future major ve
44
They are currently still available for backwards compatibility, but should not be used in new code.
55

66
- [Deprecated](#deprecated)
7-
- [RegExp .option() parameter](#regexp-option-parameter)
8-
- [noHelp](#nohelp)
9-
- [Default import of global Command object](#default-import-of-global-command-object)
10-
- [Callback to .help() and .outputHelp()](#callback-to-help-and-outputhelp)
11-
- [.on('--help')](#on--help)
12-
- [.on('command:\*')](#oncommand)
13-
- [.command('\*')](#command)
14-
- [cmd.description(cmdDescription, argDescriptions)](#cmddescriptioncmddescription-argdescriptions)
15-
- [InvalidOptionArgumentError](#invalidoptionargumenterror)
16-
- [Short option flag longer than a single character](#short-option-flag-longer-than-a-single-character)
17-
- [Import from `commander/esm.mjs`](#import-from-commanderesmmjs)
18-
- [cmd.\_args](#cmd_args)
19-
20-
## RegExp .option() parameter
7+
- [RegExp .option() parameter](#regexp-option-parameter)
8+
- [noHelp](#nohelp)
9+
- [Callback to .help() and .outputHelp()](#callback-to-help-and-outputhelp)
10+
- [.on('--help')](#on--help)
11+
- [.on('command:\*')](#oncommand)
12+
- [.command('\*')](#command)
13+
- [cmd.description(cmdDescription, argDescriptions)](#cmddescriptioncmddescription-argdescriptions)
14+
- [InvalidOptionArgumentError](#invalidoptionargumenterror)
15+
- [Short option flag longer than a single character](#short-option-flag-longer-than-a-single-character)
16+
- [Import from `commander/esm.mjs`](#import-from-commanderesmmjs)
17+
- [cmd.\_args](#cmd_args)
18+
- [.addHelpCommand(string|boolean|undefined)](#addhelpcommandstringbooleanundefined)
19+
- [Removed](#removed)
20+
- [Default import of global Command object](#default-import-of-global-command-object)
21+
22+
### RegExp .option() parameter
2123

2224
The `.option()` method allowed a RegExp as the third parameter to restrict what values were accepted.
2325

@@ -29,7 +31,7 @@ Removed from README in Commander v3. Deprecated from Commander v7.
2931

3032
The newer functionality is the Option `.choices()` method, or using a custom option processing function.
3133

32-
## noHelp
34+
### noHelp
3335

3436
This was an option passed to `.command()` to hide the command from the built-in help:
3537

@@ -39,28 +41,7 @@ program.command('example', 'example command', { noHelp: true });
3941

4042
The option was renamed `hidden` in Commander v5.1. Deprecated from Commander v7.
4143

42-
## Default import of global Command object
43-
44-
The default import was a global Command object.
45-
46-
```js
47-
const program = require('commander');
48-
```
49-
50-
The global Command object is exported as `program` from Commander v5, or import the Command object.
51-
52-
```js
53-
const { program } = require('commander');
54-
// or
55-
const { Command } = require('commander');
56-
const program = new Command()
57-
```
58-
59-
- Removed from README in Commander v5.
60-
- Deprecated from Commander v7.
61-
- Removed from TypeScript declarations in Commander v8.
62-
63-
## Callback to .help() and .outputHelp()
44+
### Callback to .help() and .outputHelp()
6445

6546
These routines allowed a callback parameter to process the built-in help before display.
6647

@@ -78,7 +59,7 @@ console.error(colors.red(program.helpInformation()));
7859

7960
Deprecated from Commander v7.
8061

81-
## .on('--help')
62+
### .on('--help')
8263

8364
This was the way to add custom help after the built-in help. From Commander v3.0.0 this used the custom long help option flags, if changed.
8465

@@ -103,7 +84,7 @@ Examples:
10384

10485
Deprecated from Commander v7.
10586

106-
## .on('command:*')
87+
### .on('command:*')
10788

10889
This was emitted when the command argument did not match a known subcommand (as part of the implementation of `.command('*')`).
10990

@@ -114,7 +95,7 @@ or for custom behaviour catch the `commander.unknownCommand` error.
11495

11596
Deprecated from Commander v8.3.
11697

117-
## .command('*')
98+
### .command('*')
11899

119100
This was used to add a default command to the program.
120101

@@ -134,7 +115,7 @@ program
134115

135116
Removed from README in Commander v5. Deprecated from Commander v8.3.
136117

137-
## cmd.description(cmdDescription, argDescriptions)
118+
### cmd.description(cmdDescription, argDescriptions)
138119

139120
This was used to add command argument descriptions for the help.
140121

@@ -157,7 +138,7 @@ program
157138

158139
Deprecated from Commander v8.
159140

160-
## InvalidOptionArgumentError
141+
### InvalidOptionArgumentError
161142

162143
This was used for throwing an error from custom option processing, for a nice error message.
163144

@@ -187,13 +168,13 @@ function myParseInt(value, dummyPrevious) {
187168

188169
Deprecated from Commander v8.
189170

190-
## Short option flag longer than a single character
171+
### Short option flag longer than a single character
191172

192173
Short option flags like `-ws` were never supported, but the old README did not make this clear. The README now states that short options are a single character.
193174

194175
README updated in Commander v3. Deprecated from Commander v9.
195176

196-
## Import from `commander/esm.mjs`
177+
### Import from `commander/esm.mjs`
197178

198179
The first support for named imports required an explicit entry file.
199180

@@ -209,7 +190,7 @@ import { Command } from 'commander';
209190

210191
README updated in Commander v9. Deprecated from Commander v9.
211192

212-
## cmd._args
193+
### cmd._args
213194

214195
This was always private, but was previously the only way to access the command `Argument` array.
215196

@@ -224,3 +205,48 @@ const registeredArguments = program.registeredArguments;
224205
```
225206

226207
Deprecated from Commander v11.
208+
209+
### .addHelpCommand(string|boolean|undefined)
210+
211+
This was originally used with a variety of parameters, but not by passing a Command object despite the "add" name.
212+
213+
```js
214+
program.addHelpCommand('assist [command]');
215+
program.addHelpCommand('assist', 'show assistance');
216+
program.addHelpCommand(false);
217+
218+
```
219+
220+
In new code you configure the help command with `.helpCommand()`. Or use `.addHelpCommand()` which now takes a Command object, like `.addCommand()`.
221+
222+
```js
223+
program.helpCommand('assist [command]');
224+
program.helpCommand('assist', 'show assistance');
225+
program.helpCommand(false);
226+
227+
program.addHelpCommand(new Command('assist').argument('[command]').description('show assistance'));
228+
229+
```
230+
## Removed
231+
232+
### Default import of global Command object
233+
234+
The default import was a global Command object.
235+
236+
```js
237+
const program = require('commander');
238+
```
239+
240+
The global Command object is exported as `program` from Commander v5, or import the Command object.
241+
242+
```js
243+
const { program } = require('commander');
244+
// or
245+
const { Command } = require('commander');
246+
const program = new Command()
247+
```
248+
249+
- Removed from README in Commander v5.
250+
- Deprecated from Commander v7.
251+
- Removed from TypeScript declarations in Commander v8.
252+
- Removed from CommonJS in Commander v12. Deprecated and gone!

‎index.js

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,11 @@ const { CommanderError, InvalidArgumentError } = require('./lib/error.js');
44
const { Help } = require('./lib/help.js');
55
const { Option } = require('./lib/option.js');
66

7-
/**
8-
* Expose the root command.
9-
*/
7+
exports.program = new Command();
108

11-
exports = module.exports = new Command();
12-
exports.program = exports; // More explicit access to global command.
13-
// createArgument, createCommand, and createOption are implicitly available as they are methods on program.
9+
exports.createCommand = (name) => new Command(name);
10+
exports.createOption = (flags, description) => new Option(flags, description);
11+
exports.createArgument = (name, description) => new Argument(name, description);
1412

1513
/**
1614
* Expose classes

‎lib/argument.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ class Argument {
5050
}
5151

5252
/**
53-
* @api private
53+
* @package internal use only
5454
*/
5555

5656
_concatValue(value, previous) {
@@ -130,7 +130,7 @@ class Argument {
130130
*
131131
* @param {Argument} arg
132132
* @return {string}
133-
* @api private
133+
* @private
134134
*/
135135

136136
function humanReadableArgName(arg) {

0 commit comments

Comments
 (0)