addCommonOption for options common to subcommands

[shadowspawn]

Pull Request

Problem

Sometimes people would like to be able to add common (global) options to all the subcommands, rather than to the program. This was the most popular enhancement in poll #1551 (comment)

Related:

• Accessing parent options from subcommand #243 so they're all already populated with the common options
• Global Options #476 add global options to a program that is applied to all commands
• Collect: global option parsing and values #1229 (comment) a set of common options for all my subcommands
• Options shared by a root command and its subCommands #1426 an option that I add to all the commands of my application
• Adding options after commands have been created #1631 add global options to each of the commands

Solution

• add .addCommonOption()
• implemented using .copyCommonOptions()
• following same pattern as .copyInheritedSettings(), and common settings are automatic for .command() but manual for .addCommand()

This is implemented for one level deep. The common options are added to direct subcommands and not sub sub commands, as don't have a good way of identifying leaf vs non-leaf commands at the time they are added.

Why not .commonOption() matching .option()? Because would need more variations to cover .requiredOption() and .addOption().

Example Usage

const { program, Option } = require('commander');

program
  .addCommonOption(new Option('-d, --debug'))
  .addCommonOption(new Option('--quiet'));

program
  .command('sub')
  .option('-l, --local')
  .action(() => {
    console.log('Thanks for calling sub');
  });

program.parse();

$ node index.js help sub
Usage: index sub [options]

Options:
  -d, --debug
  --quiet
  -l, --local
  -h, --help   display help for command

ChangeLog

[shadowspawn]

There is not a load of code in this PR which makes me realise this could be done manually fairly simply. Some of the linked issues use subclasses for implementing, here is a similar direct approach.

// Add common options after setting up program and subcommands
program.commands.forEach((cmd) => {
   cmd.option('-d, --debug');
   cmd.option('--quiet');
});

And with this approach can use .option() or .requiredOption() or .addOption(), or add event listeners, so more flexible than .addCommonOption().

Perhaps I should just add some example files showing how to do it yourself!

[shadowspawn]

This implementation was more limited and less useful than I expected. Lot of scenarios. Considerations are:

• .option() vs .requiredOption() vs .addOption()
• listeners for option events
• separately created commands (added using .addCommand()) should get some control
• besides .command(), do common options get added for .addCommand() or .createCommand() ?

Current plan is write some examples on how to do it yourself with a simple loop, and maybe a simple subclass.