Add default_selector and improve documentation on host labels and sel…

…ection (#3247)

* Add default_selector configuration functionality

* Add documentation about host labels, selectors and default_selector.

* Add documentation about host labels, selectors and default_selector.

---------

Co-authored-by: Anton Medvedev <anton@medv.io>

docs/UPGRADE.md

@@ -77,7 +77,7 @@
     ```
 11. Replace `local()` tasks with combination of `once()` and `runLocally()` func.
 12. Replace `locateBinaryPath()` with `which()` func.
-13. Configuration property `default_stage` is not supported anymore and has been dropped.
+13. Replace `default_stage` with `default_selector`, and adjust the value accordingly (for example: "prod" to "stage=prod").
 14. Replace `onHosts()` and `onStage()` with [labels & selectors](selector.md).
 15. Replace `setPrivate()` with [`hidden()`](tasks.md#hidden).
 16. Configuration property `writable_recursive` defaults to `false`. This behaviour can be overridden with:

docs/basics.md

@@ -6,6 +6,8 @@ A **recipe** is a file containing definitions for **hosts** and **tasks**.
 
 Deployer CLI requires two arguments to run: a **task** to run and a **selector**.
 
+Hosts can also be [selected via labels](hosts.md#labels), also a default host selection can be configured.
+
 ```
 $ dep deploy deployer.org
   --- ------ ------------
@@ -54,6 +56,10 @@ task my_task
 $
 ```
 
+If no host is provided and no default_selector is set, Deployer will show an interactive prompt for selecting hosts.
+If your recipe contains only one host, Deployer will automatically choose it. 
+To select all hosts specify `all`.
+
 But where is our `whoami` command output? By default, Deployer runs with normal verbosity
 level and shows only the names of executed tasks. Let's increase verbosity to verbose, and
 rerun our task.

docs/hosts.md

@@ -59,6 +59,63 @@ host('example.org')
     ->setRemoteUser('deployer');
 ```
 
+## Host labels
+
+Hosts can receive labels to identify a subselection of all available hosts. This is a flexible approach to manage and deploy multiple hosts.
+The label names and values can be chosen freely. For example, a stage name can be applied: 
+
+```php
+host('example.org')
+    ->setLabels(['stage' => 'prod'])
+;
+
+host('staging.example.org')
+    ->setLabels(['stage' => 'staging'])
+;
+
+```
+The example above can be simplified without labels, by giving the host prod and staging as name, and using setHostname(...). 
+
+But for for multi server setups, labels become much more powerful:
+
+```php
+host('admin.example.org')
+    ->setLabels(['stage' => 'prod', 'role' => 'web'])
+;
+
+host('web[1:5].example.org')
+    ->setLabels(['stage' => 'prod', 'role' => 'web'])
+;
+
+host('db[1:2].example.org')
+    ->setLabels(['stage' => 'prod', 'role' => 'db'])
+;
+
+host('test.example.org')
+    ->setLabels(['stage' => 'test', 'role' => 'web'])
+;
+
+host('special.example.org')
+    ->setLabels(['role' => 'special'])
+;
+```
+
+When calling `dep deploy`, you can filter the hosts to deploy by passing a select string:
+
+```
+$ dep deploy stage=prod&role=web,role=special
+```
+
+To check for multiple labels that have to be set on the same host, you can use the `&` operator.
+To add another selection, you can use `,` as a separator.
+
+Also you can configure a default selection string, that is used when running 'dep deploy' without arguments.
+
+```php
+set('default_selector', "stage=prod&role=web,role=special");
+```
+
+
 ## Host config
 
 ### `alias`

src/Command/SelectCommand.php

@@ -49,7 +49,7 @@ protected function selectHosts(Input $input, Output $output): array
         if (!$output->isDecorated() && !defined('NO_ANSI')) {
             define('NO_ANSI', 'true');
         }
-        $selector = $input->getArgument('selector');
+        $selector = Deployer::get()->config->get('default_selector', $input->getArgument('selector'));
         $selectExpression = is_array($selector) ? implode(',', $selector) : $selector;
 
         if (empty($selectExpression)) {