fabric/fabric — pull request #1008 by wonko21 (2013-10-21 11:21:55+00:00)
Title: Loading Hosts from a file

A Parameter --hosts-file is introduced to load hosts from a
file. This file is a structured list of hosts:
*Each Host is listed on a line.
*Hosts may be organised in name spaces
*Name spaces are decalered in Brackets with a namespace path
[/org1/sub1/foo/bar/baz]
*Hosts listed below a namespace declaration are members
*Hosts listed above all namespace declarations are members of a
unnnamed root namespace

from the file only hosts that are selected will be used.

Selection of Hosts is done through the standard --hosts and
--exclude-hosts parameters.

These have been extended to understand namespace and Hosts Selections and
Placeholders Hosts from a Namespace are selected with /name/space/path:host
Namespaces and Hosts may contain * as a placeholder for "any".

* /path/to/* Looks for hosts in the name spaces below /path/to ( eg.
/path/to/hell /path/to/heaven.
* /na/me/space:* Selects all Hosts in the Namespace /na/me/space
Thus
* /path/to/*:bender Will select the host bender if it is in heaven,hell or both
* /path/to/heaven:bender Will select bender only if it is in heaven
* /path/to/heaven:* Will select all Hosts from heaven

As a special notation * will select all hosts just liek *:*

The selection string may contain a ! as the first character. Ths signals exclusion

A command line of fab --hosts-file /path/to/file -H *,!/path/to/heaven:* will exclude
all Hosts from the Namespace /path/to/heaven. Thus being the same as:
--hosts-file /path/to/file -H * -x /path/to/heaven:*

Exsamples:

--hosts-file /path/to/file -H host1 Will only use Host1. So it is basically useless.
--hosts-file /path/to/file -H * Will use all Hosts form the file.
--hosts-file /path/to/file -H /na/me/* Will only use Hosts from the /na/me namespace.
--hosts-file /path/to/file -H /na/me/*,host1 Will also add Host1.
--hosts-file /path/to/file -H * -x /na/me/* Will use all hosts exept thos in /na/me