Add default_selector and improve documentation on host labels and selection

docs/UPGRADE.md

@@ -61,7 +61,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.
+13. Replace `default_stage` with `default_selector`, and adjust the value accordingly (for example: "prod" to "stage=prod").
 
 ## Step 2: Deploy
 

docs/basics.md

@@ -7,6 +7,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 **host**
 or group of **hosts**.
 
+Hosts can also be [selected via labels](hosts.md#labels), also a default host selection can be configured.
+
 ```
 $ dep deploy deployer.org
   --- ------ ------------
@@ -49,7 +51,7 @@ task my_task
 $  
 ```
 
-If no host provided, Deployer will show an interactive prompt for selecting hosts.
+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`.
 

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)) {