Include --uri and --root options in command line documentation

[gitressa]

Is your feature request related to a problem? Please describe.
It looks like the --uri and --root options are not available via the command line documentation.

With this command, you can see all available Drush commands:
drush list

To see options for a single command:
drush help uli

Neither --uri (drush uli --uri=https://example.org) nor -l (drush uli -l https://example.org) options are shown.

Also drush search-api:index --uri=https://example.org will work, but you can't see this under drush help search-api:index, since the --uri option isn't listed.

Describe the solution you'd like
Could we show global options, perhaps as a an extra section when issuing the drush list command, like Options?

$ drush list
Available commands:
_global:
  browse              Display a link to a given path or open link in a browser.                               
  deploy              Run several commands after performing a code deployment. 
...
Options:
  --uri[=BASE_URL]    Define site URL.
  --root[=ROOT_PATH]  Define Drupal root as an absolute path.

Alternatively, include them under Options, in the 'help' view of a single command:

$ drush help uli
Display a one time login link for user ID 1, or another user.

Examples:
  drush user:login                                         Open default web browser and browse to homepage, logged in as uid=1.                                                        
[...]
Options:
  --name[=NAME]                 A user name to log in as.                                                               
  --uid[=UID]                   A uid to log in as.                                                                     
  --mail[=MAIL]                 A user mail address to log in as.                                                       
  --browser[=BROWSER]           Optional value denotes which browser to use (defaults to operating system default).
  --redirect-port=REDIRECT-PORT A custom port for redirecting to (e.g., when running within a Vagrant environment)      
  --no-browser                  Negate --browser option.                                                                
  --uri[=BASE_URL]              Define site URL. <<--- INCLUDE IT HERE

[weitzman]

Thanks for bringing this up.

Drush currently provides help about its global options via the drush topic command. Run that and pick the very first option in the menu. Or skip the menu with drush topic core:global-options. Perhaps you haven't discovered that, and likely many others haven't either. We do advertise drush topic when you run drush list (or just drush). Likewise we advertise them in Usage.

The 2 improvements you mention sound OK - we'd have to decide which global options to list. There are too many to list them all IMO. Here is the output of drush topic core:global-options

+----------------------+------------------------------------------------------------------------------------------------------------------------+
| Name                 | Description                                                                                                            |
+----------------------+------------------------------------------------------------------------------------------------------------------------+
| --alias-path         | Specifies the list of paths where drush will search for alias files.                                                   |
| --ansi               | Force ANSI output                                                                                                      |
| --config             | Specify an additional config file to load. See example.drush.yml                                                       |
| --include            | A list of additional directory paths to search for Drush commands. Commandfiles should be placed in a subfolder called |
|                      | 'Commands'.                                                                                                            |
| --local              | Don't look in global locations for commandfiles, config, and site aliases                                              |
| --no                 | Cancels at any confirmation prompt.                                                                                    |
| --no-ansi            | Disable ANSI output                                                                                                    |
| --pipe               | Select the canonical script-friendly output format.                                                                    |
| --remote-host        | Run on a remote server.                                                                                                |
| --remote-user        | The user to use in remote execution.                                                                                   |
| --simulate           | Run in simulated mode (show what would have happened).                                                                 |
| --ssh-options        | A string of extra options that will be passed to the ssh command                                                       |
| --strict             | Return an error on unrecognized options. --strict=0: Allow unrecognized options.                                       |
| -D, --define         | Define a configuration item value.                                                                                     |
| -V, --version        | Display this application version                                                                                       |
| -d, --debug          | Equivalent to -vv                                                                                                      |
| -h, --help           | Display this help message                                                                                              |
| -l, --uri            | Which multisite from the selected root to use.                                                                         |
| -n, --no-interaction | Do not ask any interactive question                                                                                    |
| -q, --quiet          | Do not output any message                                                                                              |
| -r, --root           | The Drupal root for this site.                                                                                         |
| -v|vv|vvv, --verbose | Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug                     |
| -y, --yes            | Equivalent to --no-interaction.                                                                                        |
+----------------------+----------------------------------------

[greg-1-anderson]

Making the --uri option more visible makes sense. We shouldn't make --root more visible, though, because this option is only available in the global installation method, which is deprecated.

[gitressa]

Thanks for a fast response. I totally missed the text about drush topic, but great to know it exists, I really appreciate the very detailed documentation. Perhaps it could also be included under _global?

$ drush
Run `drush help [command]` to view command-specific help.  Run `drush topic` to read even more documentation.
Available commands: 
 _global:
browse   Display a link to a given path or open link in a browser. 
deploy   Run several commands after performing a code deployment. 
[...]
topic    Detailed documentation on options, scripting, Bashrc customization, site aliases and much more.

I agree that from the Topics list, -l, --uri would the most relevant option to include, --root not so much.

[weitzman]

The topic command appears in core:

core:topic (topic) Read detailed documentation on a given topic.

I'll leave this open for the --uri option.

[gitressa]

Sure, there's just so much more, and like I wrote -- it is easily missed. Like I also wrote, much time has been spent on making the detailed and great documentation. So maximum exposure would both help the users, as well as you guys from answering questions which are already well-documented.

But I respect your decision, and just sharing my 2 cents.

[frob]

I just came here because I was trying to find out what happened to the uri option. I would have never thought to look at topic. Maybe topic is a more common pattern in symphony commands and I need to adjust my expectations.

As it stands, with a fresh install of drush 10 running drush to get all the commands, I get this output in the global section.

$ drush
Drush Commandline Tool 10.4.3

Run `drush help [command]` to view command-specific help.  Run `drush topic` to read even more documentation.

 Available commands:
 _global:
   browse                                                                     Display a link to a given path or open link in a browser.
   drupal:directory (dd)                                                      Return the filesystem path for modules/themes and other key folders.
   generate (gen)                                                             Generate boilerplate code for modules/plugins/services etc.
   help                                                                       Display usage details for a command.
   jn:get                                                                     Execute a JSONAPI request.
   list                                                                       List available commands.
   mk:docs                                                                    Build a Markdown document for each Drush command thats available on a site.
   runserver (rs, serve)                                                      Runs PHP's built-in http server for development.
   version                                                                    Show Drush version.
   views-bulk-operations:execute (vbo-execute, vbo-exec)                      Execute an action on all results of the specified view.

Notice the vbo-execute and jn:get commands don't really seem like they belong. Should I open new issues for those?

[weitzman]

jn:get is a drush core command (and it does belong IMO) and vbo-ececute comes from one of your modules. If that command declares a category it would not show up in the _global category

[frob]

So it is. I will open an issue on that module's issue queue. Thanks for the quick reply.