Help does not output newline after the help message

[jaredpetersen]

Help should output a newline after the message.

Expected:

$ ./cli.js

  Usage: my-app [options] [command]

  Options:

    -v, --version    output the version number
    -h, --help       output usage information

  Commands:

    start [options]  start the app

$ 

Actual:

$ ./cli.js

  Usage: my-app [options] [command]

  Options:

    -v, --version    output the version number
    -h, --help       output usage information

  Commands:

    start [options]  start the app
$ 

Source:

#!/usr/bin/env node

'use strict';

const program = require('commander');
const version = require('./package.json').version;

process.title = 'my-app';

program
  .name('my-app')
  .version(version, '-v, --version');

program
  .command('start')
  .description('start the app')
  .option('-d, --directory <directory>', 'directory for the thing')
  .option('-p, --port <port>', 'port number for the thing', parseInt)
  .action(() => console.log('started'));

program.parse(process.argv);

if (!program.args.length) program.help();

Somewhat related to #732 but the description newline issue has been fixed since 2.11.0 but the line after options/commands has not.

[jaredpetersen]

According to the README, you should be able to add custom help with the following and have it display with the correct vertical padding:

program.on('--help', function(){
  console.log('  Examples:');
  console.log('');
  console.log('    $ custom-help --help');
  console.log('    $ custom-help -h');
  console.log('');
});

Adding that to my previous example shows that is not the case:

#!/usr/bin/env node

'use strict';

const program = require('commander');
const version = require('./package.json').version;

process.title = 'my-app';

program
  .name('my-app')
  .version(version, '-v, --version');

program
  .command('start')
  .description('start the app')
  .option('-d, --directory <directory>', 'directory for the thing')
  .option('-p, --port <port>', 'port number for the thing', parseInt)
  .action(() => console.log('started'));

program.on('--help', function(){
  console.log('  Examples:');
  console.log('');
  console.log('    $ custom-help --help');
  console.log('    $ custom-help -h');
  console.log('');
});

program.parse(process.argv);

if (!program.args.length) program.help();

$ ./cli.js

  Usage: my-app [options] [command]

  Options:

    -v, --version    output the version number
    -h, --help       output usage information

  Commands:

    start [options]  start the app
  Examples:

    $ custom-help --help
    $ custom-help -h

$

[jaredpetersen]

This also is a problem for subcommands like:

$ ./cli.js start --help

  Usage: start [options]

  start the app

  Options:

    -d, --directory <directory>  directory for the thing
    -p, --port <port>            port number for the thing
    -h, --help                   output usage information
$

[mojavelinux]

Why is this desirable? Now there is an extra line at the end of the output. No program I know of on Linux adds a blank line at the end of the help text. (e.g., docker help version). Now commander is producing non-standard output.

[jaredpetersen]

@mojavelinux -

All of the output examples in the README show a newline at the end of the help output and were incorrect before the pull request. Additionally, the example in the Custom Help section of the README did not work without the change. The documentation could easily be modified, but I assumed it was desirable since the newline at the end of the output was documented.

I personally think the change is more visually appealing since it evens out the starting newline (before the "Usage" text).

I agree that there should not be a newline after normal program output. There does appear to be a standard there and it's shown in the README. However, I don't think there really is a standard when it comes to help output.

Here's a small survey of how a few programs handle help:

• Docker: 1 line before help, 0 lines after help
• Node.js: 0 lines before help, 0 lines after help
• FFmpeg: 0 lines before help, 2 lines after help
• Raspivid: 0 lines before help, 1 line after help

I can get on board with removing the newline at the end of the output if the newline at the beginning is also removed; at least there would by visual symmetry and it appears to be slightly more common.

However, changing the output further would arguably constitute as a breaking change and would need to be a major revision. The previous newline addition was basically a bugfix since all of the documentation relied on it existing. Any future help output change is a behavior change.

@vanesyan @abetomo What are your thoughts on this discussion?

[roman-vanesyan]

Heh, when I approved the pr I test the output on several console programs on CLI and indeed all they printed extra line. But now I see that I forgot about the fact that I'd modified my bash console and had added extra line to PS1 on my own.

Now I can confirm that no enough popular programs print extra newline at the end of help message, tested on docker, apt, git, bash, node.

May be we should revert the commit and release patch version of 2.17 as well as remove all mentions about help in documentation.

[abetomo]

If there are many tools without line breaks, it seems better to revert #833.

[jaredpetersen]

What are the thoughts on removing the newline before the help output? apt, git, bash, node, and ffmpeg do not have this but commander does. docker includes it too but it's not in the majority in this case.

If we're already going back to fix the documentation and revert the change, I think it's worth a look.

I'd also suggest not fully reverting the change, as the number of lines in the help output was previously untested. I think a new pull request with the removal of the newline, an update of the test, and an update of the documentation is a better way to go.

[jaredpetersen]

Going to close this out since a PR was issued and merged. Any future work around removing the newline below and/or above the help output and fixing the documentation can be a new issue.

[mojavelinux]

Just to be clear, does that mean the change is not being reverted? Or that it will be only be if a new issue is submitted?

As per the discussion, I think ffmpeg should not be factored in. That program has extremely sloppy help output. We should look at programs with more proper help, such as dnf, apt-get, git, node, awk, grep, man, gcc, and so forth. None of these commands put a blank line above or below the help. And sections are separated by a single blank line.

I'll share that what I do to solve this problem is override the helpInformation() method and clean up all the excess whitespace. So it's not really a showstopper for me either way. I'm just concerned that commander is introducing inconsistency in the ecosystem of tools. I'm particularly displeased to see yarn inherit this inconsistency because it relies on commander.

[jaredpetersen]

@mojavelinux I'm not sure. Like I mentioned earlier, I'm more okay with reverting this as long as the newline above is removed as well which it looks like you agree with. I'm not sure what the maintainers' thoughts are on this are though. They seem to be pretty busy.

No matter what we do, it needs to be a new PR that fixes the documentation as well. Just a straight reversion lands us back where we were: somewhat-desirable help output with incorrect docs.

If everyone agrees on the new proposed format (0 newlines before help and 0 newlines after help), we can create a new issue and work towards a PR for this.

[roman-vanesyan]

Hello there sorry for delay. You are pretty welcome to send pr to revert this change as I have no time to work on it. Thanks

[jaredpetersen]

@mojavelinux ^^ Added a new issue to track this change.