.eslintrc.js

@@ -9,9 +9,9 @@ const javascriptSettings = {
     'no-var': 'warn',
     'one-var': 'off',
     'space-before-function-paren': ['error', 'never'],
-    'semi': ['error', 'always']
-  },
-}
+    semi: ['error', 'always']
+  }
+};
 
 const typescriptSettings = {
   files: ['*.ts'],
@@ -24,7 +24,9 @@ const typescriptSettings = {
     'no-var': 'warn',
     'one-var': 'off',
     'space-before-function-paren': ['error', 'never'],
-    'semi': 'off',
+    // Using method rather than property for method-signature-style, to document method overloads separately.
+    '@typescript-eslint/method-signature-style': ['warn', 'method'],
+    semi: 'off',
     '@typescript-eslint/semi': ['error', 'always'],
     '@typescript-eslint/member-delimiter-style': [
       'error',
@@ -40,7 +42,7 @@ const typescriptSettings = {
       }
     ]
   }
-}
+};
 
 module.exports = {
   plugins: ['jest'],
@@ -51,4 +53,4 @@ module.exports = {
     javascriptSettings,
     typescriptSettings
   ]
-}
+};

.gitignore

@@ -3,3 +3,4 @@ node_modules
 *.sock
 .idea
 .vscode/
+coverage/

CHANGELOG.md

@@ -8,6 +8,24 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
+## [6.2.0] (2020-10-25)
+
+### Added
+
+- added 'tsx' file extension for stand-alone executable subcommands ([#1368])
+- documented second parameter to `.description()` to describe command arguments ([#1353])
+- documentation of special cases with options taking varying numbers of option-arguments ([#1332])
+- documentation for terminology ([#1361])
+
+### Fixed
+
+- add missing TypeScript definition for `.addHelpCommand()' ([#1375])
+- removed blank line after "Arguments:" in help, to match "Options:" and "Commands:" ([#1360])
+
+### Changed
+
+- update dependencies
+
 ## [6.1.0] (2020-08-28)
 
 ### Added
@@ -308,8 +326,16 @@ if (program.rawArgs.length < 3) ...
 [#1323]: https://github.com/tj/commander.js/pull/1323
 [#1325]: https://github.com/tj/commander.js/pull/1325
 [#1326]: https://github.com/tj/commander.js/pull/1326
+[#1332]: https://github.com/tj/commander.js/pull/1332
+[#1353]: https://github.com/tj/commander.js/pull/1353
+[#1360]: https://github.com/tj/commander.js/pull/1360
+[#1361]: https://github.com/tj/commander.js/pull/1361
+[#1368]: https://github.com/tj/commander.js/pull/1368
+[#1375]: https://github.com/tj/commander.js/pull/1375
+
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[6.2.0]: https://github.com/tj/commander.js/compare/v6.1.0..v6.2.0
 [6.1.0]: https://github.com/tj/commander.js/compare/v6.0.0..v6.1.0
 [6.0.0]: https://github.com/tj/commander.js/compare/v5.1.0..v6.0.0
 [6.0.0-0]: https://github.com/tj/commander.js/compare/v5.1.0..v6.0.0-0

Readme.md

@@ -5,7 +5,7 @@
 [![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true)
 [![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=commander)
 
-The complete solution for [node.js](http://nodejs.org) command-line interfaces, inspired by Ruby's [commander](https://github.com/commander-rb/commander).
+The complete solution for [node.js](http://nodejs.org) command-line interfaces.
 
 Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
 
@@ -15,7 +15,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
   - [Options](#options)
     - [Common option types, boolean and value](#common-option-types-boolean-and-value)
     - [Default option value](#default-option-value)
-    - [Other option types, negatable boolean and flag|value](#other-option-types-negatable-boolean-and-flagvalue)
+    - [Other option types, negatable boolean and boolean|value](#other-option-types-negatable-boolean-and-booleanvalue)
     - [Custom option processing](#custom-option-processing)
     - [Required option](#required-option)
     - [Variadic option](#variadic-option)
@@ -46,6 +46,8 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
   - [Support](#support)
     - [Commander for enterprise](#commander-for-enterprise)
 
+For information about terms used in this document see: [terminology](./docs/terminology.md)
+
 ## Installation
 
 ```bash
@@ -76,18 +78,17 @@ Options are defined with the `.option()` method, also serving as documentation f
 
 The options can be accessed as properties on the Command object. Multi-word options such as "--template-engine" are camel-cased, becoming `program.templateEngine` etc. See also optional new behaviour to [avoid name clashes](#avoiding-option-name-clashes).
 
-Multiple short flags may optionally be combined in a single argument following the dash: boolean flags, the last flag may take a value, and the value.
+Multiple short flags may optionally be combined in a single argument following the dash: boolean flags, followed by a single option taking a value (possibly followed by the value).
 For example `-a -b -p 80` may be written as `-ab -p80` or even `-abp80`.
 
 You can use `--` to indicate the end of the options, and any remaining arguments will be used without being interpreted.
-This is particularly useful for passing options through to another
-command, like: `do -- git --version`.
 
-Options on the command line are not positional, and can be specified before or after other command arguments.
+Options on the command line are not positional, and can be specified before or after other arguments.
 
 ### Common option types, boolean and value
 
-The two most used option types are a boolean flag, and an option which takes a value (declared using angle brackets). Both are `undefined` unless specified on command line.
+The two most used option types are a boolean option, and an option which takes its value
+from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.  
 
 Example file: [options-common.js](./examples/options-common.js)
 
@@ -145,13 +146,13 @@ $ pizza-options --cheese stilton
 cheese: stilton
 ```
 
-### Other option types, negatable boolean and flag|value
+### Other option types, negatable boolean and boolean|value
 
-You can specify a boolean option long name with a leading `no-` to set the option value to false when used.
+You can define a boolean option long name with a leading `no-` to set the option value to false when used.
 Defined alone this also makes the option true by default.
 
 If you define `--foo` first, adding `--no-foo` does not change the default value from what it would
-otherwise be. You can specify a default boolean value for a boolean flag and it can be overridden on command line.
+otherwise be. You can specify a default boolean value for a boolean option and it can be overridden on command line.
 
 Example file: [options-negatable.js](./examples/options-negatable.js)
 
@@ -178,9 +179,10 @@ $ pizza-options --no-sauce --no-cheese
 You ordered a pizza with no sauce and no cheese
 ```
 
-You can specify an option which functions as a flag but may also take a value (declared using square brackets).
+You can specify an option which may be used as a boolean option but may optionally take an option-argument
+(declared with square brackets like `--optional [value]`).
 
-Example file: [options-flag-or-value.js](./examples/options-flag-or-value.js)
+Example file: [options-boolean-or-value.js](./examples/options-boolean-or-value.js)
 
 ```js
 program
@@ -202,14 +204,16 @@ $ pizza-options --cheese mozzarella
 add cheese type mozzarella
 ```
 
+For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).
+
 ### Custom option processing
 
-You may specify a function to do custom processing of option values. The callback function receives two parameters, the user specified value and the
-previous value for the option. It returns the new value for the option.
+You may specify a function to do custom processing of option-arguments. The callback function receives two parameters,
+the user specified option-argument and the previous value for the option. It returns the new value for the option.
 
-This allows you to coerce the option value to the desired type, or accumulate values, or do entirely custom processing.
+This allows you to coerce the option-argument to the desired type, or accumulate values, or do entirely custom processing.
 
-You can optionally specify the default/starting value for the option after the function.
+You can optionally specify the default/starting value for the option after the function parameter.
 
 Example file: [options-custom-processing.js](./examples/options-custom-processing.js)
 
@@ -282,7 +286,7 @@ error: required option '-c, --cheese <type>' not specified
 ### Variadic option
 
 You may make an option variadic by appending `...` to the value placeholder when declaring the option. On the command line you
-can then specify multiple option arguments, and the parsed option value will be an array. The extra arguments
+can then specify multiple option-arguments, and the parsed option value will be an array. The extra arguments
 are read until the first argument starting with a dash. The special argument `--` stops option processing entirely. If a value
 is specified in the same argument as the option then no further values are read.
 
@@ -311,6 +315,8 @@ Options:  { number: [ '1', '2', '3' ], letter: true }
 Remaining arguments:  [ 'operand' ]
 ```
 
+For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).
+
 ### Version option
 
 The optional `version` method adds handling for displaying the command version. The default option flags are `-V` and `--version`, and when present the command prints the version number and exits.
@@ -335,7 +341,7 @@ program.version('0.0.1', '-v, --vers', 'output the current version');
 
 You can specify (sub)commands using `.command()` or `.addCommand()`. There are two ways these can be implemented: using an action handler attached to the command, or as a stand-alone executable file (described in more detail later). The subcommands may be nested ([example](./examples/nestedCommands.js)).
 
-In the first parameter to `.command()` you specify the command name and any command arguments. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.
+In the first parameter to `.command()` you specify the command name and any command-arguments. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.
 
 You can use `.addCommand()` to add an already configured subcommand to the program.
 
@@ -363,21 +369,30 @@ program
   .addCommand(build.makeBuildCommand());
 ```
 
-Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `true` for `opts.hidden` will remove the command from the generated help output. Specifying `true` for `opts.isDefault` will run the subcommand if no other subcommand is specified ([example](./examples/defaultCommand.js)).
+Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will 
+remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
+subcommand is specified ([example](./examples/defaultCommand.js)).
 
 ### Specify the argument syntax
 
-You use `.arguments` to specify the arguments for the top-level command, and for subcommands they are usually included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required input. Square brackets (e.g. `[optional]`) indicate optional input.
+You use `.arguments` to specify the expected command-arguments for the top-level command, and for subcommands they are usually
+included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required command-arguments.
+Square brackets (e.g. `[optional]`) indicate optional command-arguments.
+You can optionally describe the arguments in the help by supplying a hash as second parameter to `.description()`.
 
 Example file: [env](./examples/env)
 
 ```js
 program
   .version('0.1.0')
   .arguments('<cmd> [env]')
+  .description('test command', {
+    cmd: 'command to run',
+    env: 'environment to run test in'
+  })
   .action(function (cmd, env) {
-    console.log('command:', cmdValue);
-    console.log('environment:', envValue || 'no environment given');
+    console.log('command:', cmd);
+    console.log('environment:', env || 'no environment given');
   });
 
 program.parse(process.argv);