Commander.js: Triage: Git-style subcommands

[shadowspawn]

Executable lookup

The file layout and lookup for doing subcommands is not customisable.

Issues:

• #481 Please add .command() function a path config
• #532 Allow user to specify which script a subcommand should call
• #826 Possible to specify executable for subcommands?
• #875 override basePath where commands for git-style sub-commands are fetched from

Pull Requests:

• #854 Implement specification of subcommand
• #830 Subcommands broken if bin name is different from name of script it resolves to

Lookup varies by filename/package/platform

Issues:

• #714 Git style commands and different than module name bin command issue
• #785 Git-style subcommands not working if files are implicit '.js' but command is ran without '.js'
• #786 (1) does not exist, try --help
• #890 Git-style sub-commands not working on Windows

Sub subcommands

When subcommands are scaled up to doing sub subcommands, people want easier approaches or nicer layout.

• https://github.com/tj/commander.js/issues/521#issuecomment-450038996 how to use sub command with option?
• https://github.com/tj/commander.js/issues/764#issuecomment-399739989 Subcommands syntax and usage

Pull Requests:

• #245 Completed nested command support

Allow other executables

Pull Requests:

• #604 Fixing git style subcommands on Windows & allowing subcommands to come from dependency modules

Help

Pull Requests:

• #828 Allow custom usage message to override program name for git-style sub-commands

Early history

And where it all began...

• #1 nested subcommands

[emilyrohrbough]

@shadowspawn I recently discovered the ability to define subcommand using commandar. Its great! I have run into a few different issues - the initial ones being that I use a Mac and our project configuration results in the incorrect file resolution for sub-commends. (See below for project context). I've been able to play around a bit to propose a possible fix to the issue you've called out on https://github.com/tj/commander.js/pull/604#issuecomment-483067174

(I think the next direction we want to explore with git-style commands is more control over how the commands are found. Source file naming and directory layout is one form of that, but search paths where the commands are looked for is another as in this Pull Request. i.e. installed node_modules, search path for commands like npm uses, etc.)

It seems like explicating allowing the consumer to define the root directory path would resolve this issue:

commander
  .rootDir(__dirname) // fallback to bin exec path if undefined
  .command('compile', 'compile source code')

OR

commander
  .command('compile', 'compile source code', { scriptPath: path.resolve(__dirname, 'my-script-compile') })

Project Context

/.bin
    /run-script.js // references ../scripts/run-script/run-script.js
/scripts
    /other-scripts // non-released scripts relative to my project
    /run-script
         /run-script.js
         /run-script-compile.js
         /run-script-test.js
package.json

```json
// package.json
"bin": { "run-script": "./bin/run-script" },

```bash
>> node ./bin/run-script compile
error: run-script-compile(1) does not exist, try --help

>> node scripts/my-script/run-script.js compile
**successful**

[shadowspawn]

Thanks @emilyrohrbough

Edit: I retracted this idea after understanding the current implementation better.

I'll share my idea for the syntax for a single command. I like the idea of a routine to match .action but for git-style subcommands. The current behaviour with the mode switching between action based and executable based depending on where you put the description is confusing and this could make it more obvious and symmetrical, even with no custom settings. And provide a place to put custom settings that are specific to executable and not action based. I do not have a great name yet, but something like (using settings from your example):

  .command('internal')
  .action(() => {
    // code goes here
  });

commander
  .command('external-1')
  .exec(); // Uses existing lookup

commander
  .command('external-2')
  . exec({ scriptPath: path.resolve(__dirname, 'my-script-compile') });

[emilyrohrbough]

@shadowspawn I like that too! Def more explicit.

[holmrenser]

You should probably add #828 to this.

[shadowspawn]

@holmrenser Not quite what I had in mind originally, but done. Thanks. 🙂

[shadowspawn]

Pull Request #999 is being considered for v3, adds option to override executable file name

[Piccirello]

Is this issue fixed now that v3 has been released?

[shadowspawn]

Around half of the referenced issues are now closed, and executableFileallows a work-around for some of the open issues, but there are still multiple open issues. In particular, I want to investigate the lookup differences across platforms.

[shadowspawn]

This triage issue has been inactive for a while, and no longer feels to me like a call to action. The improvements to the README to make action/executable conventions clearer, the addition of executableFile, and ongoing work on nested subcommands for action handlers address the major themes.

Closing as suggested by @Piccirello !