sttk / gulp-showhelp

Gulp plugin to show a help message for your gulpfile.js.

gulp-showhelp

Gulp plugin to show a help message for your gulpfile.js.

Install

Install gulp-showhelp with npm:

$ npm install --save-dev gulp-showhelp

Usage

First, load gulp-showhelp module and add a task to show a help message in your gulpfile.js like following:

var gulp = require('gulp');
var ghelp = require('gulp-showhelp');

gulp.task('help', function() {
  ghelp.show();
}).help = 'shows this help message.'; 

Then, you can show a help message about help task via gulp help.

$ gulp help
[gulp] Starting 'help'...

Usage
  gulp task

Tasks
  help : shows this help message.

[gulp] Finished 'help' after 557 μs

Next, add a description to each tasks. There are three types to add.

Add a task description

1. Task only

If you want to show a description about a task with no option, add help property as a string to a task object, e.g.:

gulp.task('lint', function() {
  ...
}).help = 'lints all js files.';

The result is:

$ gulp help
[gulp] Starting 'help'...

Usage
  gulp task

Tasks
  help : shows this help message.
  lint : lints all js files. 

[gulp] Finished 'help' after 660 μs

2. Task with options

If you want to show a description about a task with some options, add help property as an object to a task object. A value of a propery of which a key is an empty string is treated as a task description.

gulp.task('compile', function() {
  ...
}).help = {
  '': 'compiles source files.',
  '--srcs=pattern': 'specifys a path pattern of source files.',
  '--dest=path': 'specifys a file path.'
};

The result is:

$ gulp help
[gulp] Starting 'help'...

Usage
  gulp task [ option ... ]

Tasks
  help    : shows this help message.
  lint    : lints all js files. 
  compile : compiles source files.
    --srcs=pattern : specifys a path pattern of source files.
    --dest=path : specifys a file path.

[gulp] Finished 'help' after 753 μs

3. Free description using a function

If you want to show a free format description about a task, add help property as a function to a task object. You can use showTask function to show a task description and showOption function to show a option description.

gulp.task('test', function(){
  ...
}).help = function() {
  ghelp.showTask('test', 'tests modules.');
  ghelp.showOption('--case=id', 'specifys a test case ID.');
  var text = '\n' +
    '    Test case IDs:\n' +
    '        ID  :        description\n' +
    '      ------:-------------------------------------\n' +
    '      case1 : .... \n' +
    '      case2 : .... \n' +
    '      case3 : .... \n' +
    '';
  console.log(text);
};

The result is:

$ gulp help
[gulp] Starting 'help'...

Usage
  gulp task [ option ... ]

Tasks
  help    : shows this help message.
  lint    : lints all js files. 
  compile : compiles source files.
    --srcs=pattern : specifys a path pattern of source files.
    --dest=path : specifys a file path.
  test    : tests modules.
    --case=id : specifys a test case ID.

    Test case IDs:
        ID  :        description
      ------:-------------------------------------
      case1 : .... 
      case2 : .... 
      case3 : .... 


[gulp] Finished 'help' after 934 μs

Select and order tasks

You can select and order tasks of which you want to show a description by specifying task names in order.

gulp.task('help', function() {
  ghelp.show('lint', 'help', '', 'compile');
}).help = 'shows this help message.'; 

If a null or an empty string is specified as a task name, an empty line is displayed.

Select a task via a command-line argument.

If you want to be able to select a task via a command-line argument, getArgv function is useful. Write as follows:

gulp.task('help', function() {
  var task = ghelp.getArgv('task', 't');
  if (task != null) {
    ghelp.show(task);
  } else {
    ghelp.show();
  }
}).help = {
  '': 'shows this help message.',
  '[ --task=t ]': 'specifys a task shown. Alias: -t.' 
};

APIs

API names are changed to camel case according to JavaScript coding conventions. So the functions show_task, show_option, get_argv are deprecated, but they are left for compatibility.

gulp-showhelp provides the following functions:

.show([ ...taskname ]) : Void

Shows a help message about all tasks or specified tasks in gulpfile.js.

Parameters:

Parameter	Type	Description
taskname	string	A task name. If null or empty, displays an empty line.

.show(tasknames) : Void

Shows a help message about tasks specified by an array in gulpfile.js.

Parameters:

Parameter	Type	Description
tasknames	Array	An array which contains task names.

.showTask(taskname, taskdesc) : Void

Shows a task description using a help message.

Parameter	Type	Description
taskname	string	A task name.
taskdesc	string	A task explanation.

.showOption(optionname, optiondesc) : Void

Shows a option description using a help message.

Parameter	Type	Description
optionname	string	An option name.
optiondesc	string	An option explanation.

.getArgv(optionname [, optionalias, ...]) : Void

Gets a option value corresponding to the specified option name or alias.

Parameter	Type	Description
optionname	string	An option name.
optionalias	string	An option alias.

.taskNames() : Array

Gets an array which contains all task names.

Returns:

An array of task names.

Type: Array

License

Copyright (C) 2014-2017 Takayuki Sato.

This program is free software under MIT License. See the file LICENSE in this distribution for more details.

gulp-showhelp's Issues

Add an option to sort task alphabatically

I saw that if you list the task in the show method they will be listed in the specified order. However, I would just like to see them in alphabetical order.

Is it possible to add an option to do that?

Option part in usage is not displayed though using 'show_option' function

Option part in usage is displayed only when a object-style help.
It should be displayed when using 'show_option' function in a function-style help.

Task descriptions are not aligned in v1.0.1

Start of task descriptions (and preceding colons) are not aligned.
This bug was embeded as the issue #1 was modified.

A property of a null key in an object-style help doesn't work as a task description

A property of which a key is an empty string in an object-style help is displayed as a task description well.
But a property of null key isn't display.

A key of an object is treated as a string even if it's null.
So should be displayed as a task description only when the key is an empty string.

Not work with Gulp 4

D:\WebDevelopment\Project\webdevelopment\gw_starter\node_modules\gulp-showhelp\index.js:13
return gulp.tasks[name];
^

TypeError: Cannot read property 'help' of undefined
at Gulp.gulp.task (D:\WebDevelopment\Project\webdevelopment\gw_starter\node_modules\gulp-showhelp\index.js:13:20)
at Object. (D:\WebDevelopment\Project\webdevelopment\gw_starter\gulpfile.js:16:6)
at Module._compile (module.js:649:30)
at Object.Module._extensions..js (module.js:660:10)
at Module.load (module.js:561:32)
at tryModuleLoad (module.js:501:12)
at Function.Module._load (module.js:493:3)
at Module.require (module.js:593:17)
at require (internal/module.js:11:18)
at execute (C:\Users\HP\AppData\Roaming\npm\node_modules\gulp-cli\lib\versioned^4.0.0\index.js:36:18)
at Liftoff.handleArguments (C:\Users\HP\AppData\Roaming\npm\node_modules\gulp-cli\index.js:175:63)
at Liftoff.execute (C:\Users\HP\AppData\Roaming\npm\node_modules\gulp-cli\node_modules\liftoff\index.js:203:12)
at module.exports (C:\Users\HP\AppData\Roaming\npm\node_modules\gulp-cli\node_modules\flagged-respawn\index.js:51:3)
at Liftoff. (C:\Users\HP\AppData\Roaming\npm\node_modules\gulp-cli\node_modules\liftoff\index.js:195:5)
at C:\Users\HP\AppData\Roaming\npm\node_modules\gulp-cli\node_modules\liftoff\index.js:165:9
at C:\Users\HP\AppData\Roaming\npm\node_modules\gulp-cli\node_modules\v8flags\index.js:108:14