+Site-Wide Drush Commands
+==============================
+
+Commandfiles that are installed in a Drupal site and are not bundled inside a Drupal module are called 'site-wide' commandfiles. Site-wide commands may either be added directly to the Drupal site's repository (e.g. for site-specific policy files), or via `composer require`. See the [examples/Commands](/examples/Commands) folder for examples. In general, it's better to use modules to carry your Drush commands, as module-based commands may [participate in Drupal's dependency injection via the drush.services.yml](#specifying-the-services-file).
+
+If you still prefer using site-wide commandfiles, here are some examples of valid commandfile names and namespaces:
+
+1. Simple
+ - Filename: $PROJECT_ROOT/drush/Commands/ExampleCommands.php
+ - Namespace: Drush\Commands
+1. Nested in a subdirectory committed to the site's repository
+ - Filename: $PROJECT_ROOT/drush/Commands/example/ExampleCommands.php
+ - Namespace: Drush\Commands\example
+1. Nested in a subdirectory installed via a Composer package
+ - Filename: $PROJECT_ROOT/drush/Commands/contrib/dev_modules/ExampleCommands.php
+ - Namespace: Drush\Commands\dev_modules
+
+Installing commands as part of a Composer project requires that the project's type be `drupal-drush`, and that the `installer-paths` in the Drupal site's composer.json file contains `"drush/Commands/contrib/{$name}": ["type:drupal-drush"]`. It is also possible to commit projects with a similar layout using a directory named `custom` in place of `contrib`; if this is done, then the directory `custom` will not be considered to be part of the commandfile's namespace.
+
+If a site-wide commandfile is added via a Composer package, then it may declare any dependencies that it may need in its composer.json file. Site-wide commandfiles that are committed directly to a site's repository only have access to the dependencies already available in the site. Site-wide commandfiles should declare their Drush version compatibility via a `conflict` directive. For example, a Composer-managed site-wide command that works with both Drush 8 and Drush 9 might contain something similar to the following in its composer.json file:
+```
+ "conflict": {
+ "drush/drush": "<8.1 || >=9.0 <9.5 || >=10.0",
+ }
+```
+Using `require` in place of `conflict` is not recommended.
+