This patch allows commandfiles to add options or new sections to drush commands (full command help only).

For example:

function project_issue_drush_help_alter(&$command) {
  if ($command['command'] == 'sql-sync') {
    $command['sections']['sanitizations'] = 'Sanitizations';
    $command['sanitizations']['--no-project-issue-sanitize'] = "Don't sanitize the project issue table";
  }
}

That's probably not how I'd do help alter for project issue; this just shows what is possible. Of course you can just add $command['options']['--no-project-issue-sanitize'] = ..., which would be the typical case. $command['sections'] can be defined in a commandfile as well as in help-alter, or course.

This patch also removes a small amount of code that was only useful when commands could contain spaces.

CommentFileSizeAuthor
#3 help-alter-2.patch4.03 KBgreg.1.anderson
help-alter.patch3.44 KBgreg.1.anderson

Comments

moshe weitzman’s picture

moshe weitzman commented

Well done.

Hmmm. I think we are ok but pls confirm that module owned commandfiles will be able to alter the help of any other command. Just wondering about custom bootstrapping in drush_core_help().

Should we move the help altering that engines do into this hook? See drush_show_help(). Further, we have a lot of options that are SVN specific for example. Might merit own section.

'sections' needs to be added to the big array in drush_get_commands(). thats our one place for documenting what the heck is possible in a command definition.

I might prefer a single array with a special 'title' element. Its a bit weird to separate out the title from the rest. I'm ok wither way.


$command['sections']['sanitizations'] = array(
  'title' => 'Sanitizations',
  '--no-project-issue-sanitize' = "Don't sanitize the project issue table",
);
moshe weitzman’s picture

moshe weitzman commented

Actually, the arrays you propose does lead to clean code when displaying the help so I'm good with it.

greg.1.anderson’s picture

greg.1.anderson commented
StatusFileSize
new help-alter-2.patch4.03 KB

pls confirm that module owned commandfiles will be able to alter the help of any other command.

Yep, already confirmed; that's why help bootstraps to the DRUSH_SITE level, to insure that the module-owned commandfiles are loaded. There's no way to know if we should bootstrap to this level until after we bootstrap to this level... but at least SITE is far enough, no need to go to FULL.

'sections' needs to be added to the big array in drush_get_commands()

Sure, no problem; new patch attached.

we have a lot of options that are SVN specific for example.

Maybe; it would help keep options together, if some commandfile added an svn-related option. This also begs the question of whether there should be sub-sections (the options / svn section, etc.)

Should we move the help altering that engines do into this hook?

This hook can only alter help, whereas the engine system can do other changes to the commands. I don't think I'm in favor of splitting out help from the existing engines; the extra complexity outweights the consistency, which I think is debatable anyway -- maybe it's more consistent to have the engine help where it is.

Let me know if you feel strongly about either of those other two issues.

moshe weitzman’s picture

moshe weitzman commented
Status: Needs review » Reviewed & tested by the community

don't feel strongly about those. rtbc.

in a follow-up, we should experiment with subsections like options/svn.

greg.1.anderson’s picture

greg.1.anderson commented

I'll add some docs to drush.api.php and commit shortly.

greg.1.anderson’s picture

greg.1.anderson commented
Status: Reviewed & tested by the community » Fixed

Committed.

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.