Skip to content

Commit

Permalink
Merge pull request #2140 from tj/release/12.x
Browse files Browse the repository at this point in the history
  • Loading branch information
shadowspawn authored Feb 3, 2024
2 parents b0f789f + 608eaf0 commit e3192a1
Show file tree
Hide file tree
Showing 31 changed files with 1,405 additions and 858 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ jobs:
strategy:
fail-fast: false
matrix:
node-version: [16.x, 18.x, 20.x]
node-version: [18.x, 20.x]
os: [ubuntu-latest, windows-latest, macos-latest]

steps:
Expand Down
70 changes: 70 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,63 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
<!-- markdownlint-disable MD024 -->
<!-- markdownlint-disable MD004 -->

## [12.0.0] (2024-02-03)

### Added

- `.addHelpOption()` as another way of configuring built-in help option ([#2006])
- `.helpCommand()` for configuring built-in help command ([#2087])

### Fixed

- *Breaking:* use non-zero exit code when spawned executable subcommand terminates due to a signal ([#2023])
- *Breaking:* check `passThroughOptions` constraints when using `.addCommand` and throw if parent command does not have `.enablePositionalOptions()` enabled ([#1937])

### Changed

- *Breaking:* Commander 12 requires Node.js v18 or higher ([#2027])
- *Breaking:* throw an error if add an option with a flag which is already in use ([#2055])
- *Breaking:* throw an error if add a command with name or alias which is already in use ([#2059])
- *Breaking:* throw error when calling `.storeOptionsAsProperties()` after setting an option value ([#1928])
- replace non-standard JSDoc of `@api private` with documented `@private` ([#1949])
- `.addHelpCommand()` now takes a Command (passing string or boolean still works as before but deprecated) ([#2087])
- refactor internal implementation of built-in help option ([#2006])
- refactor internal implementation of built-in help command ([#2087])

### Deprecated

- `.addHelpCommand()` passing string or boolean (use `.helpCommand()` or pass a Command) ([#2087])

### Removed

- *Breaking:* removed default export of a global Command instance from CommonJS (use the named `program` export instead) ([#2017])

### Migration Tips

**global program**

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`).

```js
// const program = require('commander');
const { program } = require('commander');
```

**option and command clashes**

A couple of configuration problems now throw an error, which will pick up issues in existing programs:

- adding an option which uses the same flag as a previous option
- adding a command which uses the same name or alias as a previous command

## [12.0.0-1] (2024-01-20)

(Released in 12.0.0)

## [12.0.0-0] (2023-11-11)

(Released in 12.0.0)

## [11.1.0] (2023-10-13)

### Fixed
Expand Down Expand Up @@ -1188,13 +1245,23 @@ program
[#1874]: https://github.com/tj/commander.js/pull/1874
[#1886]: https://github.com/tj/commander.js/pull/1886
[#1896]: https://github.com/tj/commander.js/pull/1896
[#1928]: https://github.com/tj/commander.js/pull/1928
[#1930]: https://github.com/tj/commander.js/pull/1930
[#1937]: https://github.com/tj/commander.js/pull/1937
[#1949]: https://github.com/tj/commander.js/pull/1949
[#1965]: https://github.com/tj/commander.js/pull/1965
[#1969]: https://github.com/tj/commander.js/pull/1969
[#1982]: https://github.com/tj/commander.js/pull/1982
[#1983]: https://github.com/tj/commander.js/pull/1983
[#2006]: https://github.com/tj/commander.js/pull/2006
[#2010]: https://github.com/tj/commander.js/pull/2010
[#2017]: https://github.com/tj/commander.js/pull/2017
[#2019]: https://github.com/tj/commander.js/pull/2019
[#2023]: https://github.com/tj/commander.js/pull/2023
[#2027]: https://github.com/tj/commander.js/pull/2027
[#2055]: https://github.com/tj/commander.js/pull/2055
[#2059]: https://github.com/tj/commander.js/pull/2059
[#2087]: https://github.com/tj/commander.js/pull/2087

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

[Unreleased]: https://github.com/tj/commander.js/compare/master...develop
[12.0.0]: https://github.com/tj/commander.js/compare/v11.1.0...v12.0.0
[12.0.0-1]: https://github.com/tj/commander.js/compare/v12.0.0-0...v12.0.0-1
[12.0.0-0]: https://github.com/tj/commander.js/compare/v11.1.0...v12.0.0-0
[11.1.0]: https://github.com/tj/commander.js/compare/v11.0.0...v11.1.0
[11.0.0]: https://github.com/tj/commander.js/compare/v10.0.1...v11.0.0
[10.0.1]: https://github.com/tj/commander.js/compare/v10.0.0...v10.0.1
Expand Down
14 changes: 9 additions & 5 deletions Readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
- [.usage](#usage)
- [.description and .summary](#description-and-summary)
- [.helpOption(flags, description)](#helpoptionflags-description)
- [.addHelpCommand()](#addhelpcommand)
- [.helpCommand()](#helpcommand)
- [More configuration](#more-configuration-2)
- [Custom event listeners](#custom-event-listeners)
- [Bits and pieces](#bits-and-pieces)
Expand Down Expand Up @@ -904,16 +904,20 @@ program
.helpOption('-e, --HELP', 'read more information');
```

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

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)`.
### .helpCommand()

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)`.

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

```js
program.addHelpCommand('assist [command]', 'show assistance');
program.helpCommand('assist [command]', 'show assistance');
```

(Or use `.addHelpCommand()` to add a command you construct yourself.)

### More configuration

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

## Support

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

The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.
Expand Down
2 changes: 1 addition & 1 deletion Readme_zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -1059,7 +1059,7 @@ program
## 支持
当前版本的 Commander 在 LTS 版本的 Node.js 上完全支持。并且至少需要 v16
当前版本的 Commander 在 LTS 版本的 Node.js 上完全支持。并且至少需要 v18
(使用更低版本 Node.js 的用户建议安装更低版本的 Commander)
社区支持请访问项目的 [Issues](https://github.com/tj/commander.js/issues)。
Expand Down
4 changes: 2 additions & 2 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ Old versions receive security updates for six months.

| Version | Supported |
| ------- | ------------------------------------------ |
| 10.x | :white_check_mark: support ends 2024-01-16 |
| < 10 | :x: |
| 11.x | :white_check_mark: support ends 2024-07-03 |
| < 11 | :x: |

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

Expand Down
116 changes: 71 additions & 45 deletions docs/deprecated.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,22 @@ These features are deprecated, which means they may go away in a future major ve
They are currently still available for backwards compatibility, but should not be used in new code.

- [Deprecated](#deprecated)
- [RegExp .option() parameter](#regexp-option-parameter)
- [noHelp](#nohelp)
- [Default import of global Command object](#default-import-of-global-command-object)
- [Callback to .help() and .outputHelp()](#callback-to-help-and-outputhelp)
- [.on('--help')](#on--help)
- [.on('command:\*')](#oncommand)
- [.command('\*')](#command)
- [cmd.description(cmdDescription, argDescriptions)](#cmddescriptioncmddescription-argdescriptions)
- [InvalidOptionArgumentError](#invalidoptionargumenterror)
- [Short option flag longer than a single character](#short-option-flag-longer-than-a-single-character)
- [Import from `commander/esm.mjs`](#import-from-commanderesmmjs)
- [cmd.\_args](#cmd_args)

## RegExp .option() parameter
- [RegExp .option() parameter](#regexp-option-parameter)
- [noHelp](#nohelp)
- [Callback to .help() and .outputHelp()](#callback-to-help-and-outputhelp)
- [.on('--help')](#on--help)
- [.on('command:\*')](#oncommand)
- [.command('\*')](#command)
- [cmd.description(cmdDescription, argDescriptions)](#cmddescriptioncmddescription-argdescriptions)
- [InvalidOptionArgumentError](#invalidoptionargumenterror)
- [Short option flag longer than a single character](#short-option-flag-longer-than-a-single-character)
- [Import from `commander/esm.mjs`](#import-from-commanderesmmjs)
- [cmd.\_args](#cmd_args)
- [.addHelpCommand(string|boolean|undefined)](#addhelpcommandstringbooleanundefined)
- [Removed](#removed)
- [Default import of global Command object](#default-import-of-global-command-object)

### RegExp .option() parameter

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

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

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

## noHelp
### noHelp

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

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

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

## Default import of global Command object

The default import was a global Command object.

```js
const program = require('commander');
```

The global Command object is exported as `program` from Commander v5, or import the Command object.

```js
const { program } = require('commander');
// or
const { Command } = require('commander');
const program = new Command()
```

- Removed from README in Commander v5.
- Deprecated from Commander v7.
- Removed from TypeScript declarations in Commander v8.

## Callback to .help() and .outputHelp()
### Callback to .help() and .outputHelp()

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

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

Deprecated from Commander v7.

## .on('--help')
### .on('--help')

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.

Expand All @@ -103,7 +84,7 @@ Examples:

Deprecated from Commander v7.

## .on('command:*')
### .on('command:*')

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

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

Deprecated from Commander v8.3.

## .command('*')
### .command('*')

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

Expand All @@ -134,7 +115,7 @@ program

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

## cmd.description(cmdDescription, argDescriptions)
### cmd.description(cmdDescription, argDescriptions)

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

Expand All @@ -157,7 +138,7 @@ program

Deprecated from Commander v8.

## InvalidOptionArgumentError
### InvalidOptionArgumentError

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

Expand Down Expand Up @@ -187,13 +168,13 @@ function myParseInt(value, dummyPrevious) {

Deprecated from Commander v8.

## Short option flag longer than a single character
### Short option flag longer than a single character

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.

README updated in Commander v3. Deprecated from Commander v9.

## Import from `commander/esm.mjs`
### Import from `commander/esm.mjs`

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

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

README updated in Commander v9. Deprecated from Commander v9.

## cmd._args
### cmd._args

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

Expand All @@ -224,3 +205,48 @@ const registeredArguments = program.registeredArguments;
```

Deprecated from Commander v11.

### .addHelpCommand(string|boolean|undefined)

This was originally used with a variety of parameters, but not by passing a Command object despite the "add" name.

```js
program.addHelpCommand('assist [command]');
program.addHelpCommand('assist', 'show assistance');
program.addHelpCommand(false);

```

In new code you configure the help command with `.helpCommand()`. Or use `.addHelpCommand()` which now takes a Command object, like `.addCommand()`.

```js
program.helpCommand('assist [command]');
program.helpCommand('assist', 'show assistance');
program.helpCommand(false);

program.addHelpCommand(new Command('assist').argument('[command]').description('show assistance'));

```
## Removed

### Default import of global Command object

The default import was a global Command object.

```js
const program = require('commander');
```

The global Command object is exported as `program` from Commander v5, or import the Command object.

```js
const { program } = require('commander');
// or
const { Command } = require('commander');
const program = new Command()
```

- Removed from README in Commander v5.
- Deprecated from Commander v7.
- Removed from TypeScript declarations in Commander v8.
- Removed from CommonJS in Commander v12. Deprecated and gone!
10 changes: 4 additions & 6 deletions index.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,11 @@ const { CommanderError, InvalidArgumentError } = require('./lib/error.js');
const { Help } = require('./lib/help.js');
const { Option } = require('./lib/option.js');

/**
* Expose the root command.
*/
exports.program = new Command();

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

/**
* Expose classes
Expand Down
4 changes: 2 additions & 2 deletions lib/argument.js
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ class Argument {
}

/**
* @api private
* @package internal use only
*/

_concatValue(value, previous) {
Expand Down Expand Up @@ -130,7 +130,7 @@ class Argument {
*
* @param {Argument} arg
* @return {string}
* @api private
* @private
*/

function humanReadableArgName(arg) {
Expand Down
Loading

0 comments on commit e3192a1

Please sign in to comment.