How to integrate the drush help --filter option with your custom module?

Question

You can use the drush help --filter command to present a list of command categories to view. When you run the command: drush --filter=devel_generate you can see the following output:

All commands in devel_generate: (devel_generate)
 generate-content  Create content.                       
 (genc)                                                  
 generate-menus    Create menus and menu items.          
 (genm)                                                  
 generate-terms    Create terms in specified vocabulary. 
 (gent)                                                  
 generate-users    Create users.                         
 (genu)                                                  
 generate-vocabs   Create vocabularies.                  
 (genv)

You can read in the Drush Command page:

help

Options: --filter=[category] Restrict command list to those commands defined in the specified file. Omit value to choose from a list of names.

I create the onlyone.drush.inc file with the following code:

<?php
/**
 * @file
 * Drush commands related to OnlyOne.
 */

/**
* Implements hook_drush_command().
*/
function onlyone_drush_command() {
  $items['onlyone-list'] = array(
    'description' => dt("List the configured content types to have Only One node."),
    'aliases' => array('ol'),
    'examples' => array(
      'drush onlyone-list' => dt("List the configured content types to have Only One node."),
    ),
  );
  return $items;
}

/**
 * Callback for the onlyone-list command.
 */
function drush_onlyone_list() {
  $onlyone_content_types = variable_get('onlyone_node_types');

  if (count($onlyone_content_types)) {
    drush_print(dt("Content types configured to have only one node:"));
    drush_print(implode("\n", $onlyone_content_types));
  }
  else {
    drush_print(dt("There is not content types configured to have only one node."));
  }
}

I clean the cache with drush cc drush but when I use drush help --filter=onlyone I get this output:

 [error]  The specified command category onlyone does not exist. 

So, how can I obtain the list of the commands defined in my module?

Answer 1

Here is the explanation found in the help hook (sandwich_drush_help) of the example sandwich command (examples/sandwich.drush.inc):

// The 'title' meta item is used to name a group of
// commands in `drush help`.  If a title is not defined,
// the default is "All commands in ___", with the
// specific name of the commandfile (e.g. sandwich).
// Command files with less than four commands will
// be placed in the "Other commands" section, _unless_
// they define a title.  It is therefore preferable
// to not define a title unless the file defines a lot
// of commands.
case 'meta:sandwich:title':
  return dt("Sandwich commands");

This explanation is admittedly a little obtuse. The general idea is that Drush thinks that a commandfile that defines a 'meta:MODULENAME:title' help item is important / distinct enough to get its own section in Drush help; untitled commandfiles are all grouped into the "other" section, unless they have so many commands that they would tend to make the "other" section too long, in which case they are given their own section with an arbitrary title.

The number 4 is completely arbitrary.

The --filter feature was designed to show just part of the help index; it was not really considered to be a feature to show all of the Drush commands available for a given module. There is no other good way to do that, though; it might be an improvement to simply abolish the "other" section, and put all of the commands for each commandfile into its own section. If that was done, then --filter would behave as you expected it to.

Answer 2

I found the answer searching in the code of the drush project:

If the module have less than 4 commands you can't use the drush --filter=MODULE_NAME because your commands are classified as other:

See the function drush_commands_categorize(), and at line 1125 you can see this comment:

  // Post-process the categories that have no title.
  // Any that have fewer than 4 commands go into a section called "other".

I create 3 more commands and now the drush --filter=onlyone command works.