X-Git-Url: http://www.aleph1.co.uk/gitweb/?p=yaffs-website;a=blobdiff_plain;f=vendor%2Fdrush%2Fdrush%2Fexamples%2Fexample.site.yml;fp=vendor%2Fdrush%2Fdrush%2Fexamples%2Fexample.site.yml;h=b200cf0669707246c87c812ddb027f8d2cc51226;hp=bb4818c5a6c748dad965de6877538314ba44c144;hb=0bf8d09d2542548982e81a441b1f16e75873a04f;hpb=74df008bdbb3a11eeea356744f39b802369bda3c

diff --git a/vendor/drush/drush/examples/example.site.yml b/vendor/drush/drush/examples/example.site.yml
index bb4818c5a..b200cf066 100644
--- a/vendor/drush/drush/examples/example.site.yml
+++ b/vendor/drush/drush/examples/example.site.yml
@@ -1,68 +1,74 @@
 #
 # Example of valid statements for an alias file.
+
+# Basic Alias File Usage
 #
-# To convert legacy alias (*.aliases.drushrc.php) to yml, run the
-# site:alias-convert command.
+# In its most basic form, the Drush site alias feature provides a way
+# for teams to share short names that refer to the live and staging sites
+# (usually remote) for a given Drupal site.
 #
-# Use this file as a guide to creating your own aliases.
+# 1. Make a local working clone of your Drupal site and then
+#    `cd` to the project work to select it.
+# 2. Add an alias file called $PROJECT/drush/sites/self.site.yml,
+#    where $PROJECT is the project root (location of composer.json file).
+# 3. Run remote commands against the shared live or stage sites
 #
-# Aliases are commonly used to define short names for
-# local or remote Drupal installations; however, an alias
-# is really nothing more than a collection of options.
+# Following these steps, a cache:rebuild on the live environment would be:
 #
-# Drush site aliases always contain one or more environments;
-# for example, a site may have "dev", "test" and "live"
-# environments. The default environment is "dev"; the dev
-# environment of a site named "example" may therefore be
-# referred to as either "@example.dev" or "@example".
+#   $ drush @live cache:rebuild
 #
-# A canonical alias named "example" that points to a local
-# Drupal site named "http://example.com" looks like this:
+# The site alias file should be named `self.site.yml` because this name is
+# special, and is used to define the different environments (usually remote)
+# of the current Drupal site.
+#
+# The contents of the alias file should look something like the example below:
 #
 # @code
-# File: example.site.yml
-# dev:
-#   root: /path/to/drupal
+# # File: self.site.yml
+# live:
+#   host: server.domain.com
+#   user: www-admin
+#   root: /other/path/to/live/drupal
 #   uri: http://example.com
+# stage:
+#   host: server.domain.com
+#   user: www-admin
+#   root: /other/path/to/stage/drupal
+#   uri: http://stage.example.com
 # @endcode
 #
-# Note that the first part of the filename (in this case "example")
-# defines the name of the site alias, and the top-level key ("dev")
-# defines the name of the environment.
-#
-# With this alias definition, then the following commands
-# are equivalent:
-#
-#   $ drush @example.dev status
-#   $ drush --root=/path/to/drupal --uri=http://example.com status
+# The top-level element names (`live` and `stage` in the example above) are
+# used to identify the different environments available for this site. These
+# may be used on the command line to select a different target environment
+# to operate on by prepending an `@` character, e.g. `@live` or `@stage`.
 #
-# See the --uri option documentation below for hints on setting its value.
+# All of the available aliases for a site's environments may be listed via:
 #
-# Any option that can be placed on the Drush commandline
-# can also appear in an alias definition inside an 'options' section.
-#
-# Drush will search for aliases in any of these files using
-# the alias search path.  The following locations are examined
-# for alias files:
-#
-#   1. In any path set in drush.alias-path in drush.yml
-#      or (equivalently) any path passed in via --alias-path=...
-#      on the command line.
-#   2. In one of the site-specific locations:
-#        a. The /drush/sites folder for the current Drupal site
-#        b. The /drush/sites folder in the directory above the current Drupal site
-#
-# These locations are no longer searched recursively; alias files must
-# appear directly inside one of the search locations, or it will not be found.
+#   $ drush site:alias @self
 #
-# The preferred locations for alias files, then, are:
+# The elements of a site alias environment are:
 #
-#   $ROOT/drush/sites
-#   $ROOT/../drush/sites
+# - 'host': The fully-qualified domain name of the remote system
+#   hosting the Drupal instance. **Important Note: The remote-host option
+#   must be omitted for local sites, as this option controls various
+#   operations, such as whether or not rsync parameters are for local or
+#   remote machines, and so on.
+# - 'user': The username to log in as when using ssh or rsync.
+# - 'root': The Drupal root; must not be specified as a relative path.
+# - 'uri': The value of --uri should always be the same as
+#   when the site is being accessed from a web browser (e.g. http://example.com)
 #
-# If you would like to add additional locations, you can do so by
-# listing additional locations in your configuration files. For example,
-# to re-add the default user alias path from Drush 8, put the following
+# Drush uses ssh to run commands on remote systems; all team members should
+# install ssh keys on the target servers (e.g. via ssh-add).
+
+# Advanced Site Alias File Usage
+#
+# It is also possible to create site alias files that reference other
+# sites on the same local system. Site alias files for other local sites
+# are usually stored in the directory `~/.drush/sites`; however, Drush does
+# not search this location for alias files by default. To use this location,
+# you must add the path in your Drush configuration file. For example,
+# to re-add both of the default user alias path from Drush 8, put the following
 # in your ~/.drush/drush.yml configuration file:
 #
 # @code
@@ -73,61 +79,55 @@
 #       - /etc/drush/sites
 # @endcode
 #
-# If you run the command `drush core:init`, this configuration will
-# be done for you automatically.
-#
-# Files stored in one of the search path locations can be used to create
-# aliases to local and remote Drupal installations.  These aliases can be
-# used in place of a site specification on the command line, and may also
-# be used in arguments to certain commands such as "drush rsync" and
-# "drush sql:sync".
-#
-# To see an example alias definition for the current bootstrapped
-# site, use the "site:alias" command with the built-in alias "@self":
+# The command `drush core:init` will automatically configure your
+# ~/.drush/drush.yml configuration file to add `~/.drush/sites` and
+# `/etc/drush/sites` as locations where alias files may be placed.
 #
-#   $ drush site:alias @self
-#
-# Drush also supports *remote* site aliases.  When a site alias is
-# defined for a remote site, Drush will use the ssh command to run
-# the requested command on the remote machine.  The simplest remote
-# alias looks like this:
+# A canonical alias named "example" that points to a local
+# Drupal site named "http://example.com" looks like this:
 #
 # @code
-# # File: remote.site.yml
-# live:
-#   host: server.domain.com
-#   user: www-admin
-#   root: /other/path/to/drupal
+# File: example.site.yml
+# dev:
+#   root: /path/to/drupal
 #   uri: http://example.com
 # @endcode
 #
-# Drush also treats the site alias file /drush/sites/self.site.yml
-# (in the Drupal root or project root) specially. If your current
-# working directory is inside a Drupal project, then aliases such
-# as `@self.live` may be referenced simply as `@live`. Commit the
-# file self.site.yml to your site's repository to share remote aliases
-# for a site with team members.
+# Note that the first part of the filename (in this case "example")
+# defines the name of the site alias, and the top-level key ("dev")
+# defines the name of the environment.
 #
-# The built-in alias "@none" represents the state of no Drupal site;
-# to ignore the site at the cwd and just see default drush status:
+# With these definitions in place, it is possible to run commands targeting
+# the dev environment of the target site via:
 #
-#   $ drush @none status
+#   $ drush @example.dev status
 #
-# See `drush help site:alias` for more options for displaying site
-# aliases.
+# This command is equivalent to the longer form:
 #
-# Although most aliases will contain only a few options, a number
-# of settings that are commonly used appear below:
+#   $ drush --root=/path/to/drupal --uri=http://example.com status
+#
+# See "Additional Site Alias Options" below for more information.
+
+# Converting Legacy Alias Files
+#
+# To convert legacy alias (*.aliases.drushrc.php) to yml, run the
+# site:alias-convert command.
+
+# Altering aliases:
+#
+# See examples/Commands/SiteAliasAlterCommands.php for an example.
+
+# Environment variables:
+#
+# It is no longer possible to set environment variables from within an alias.
+# This is a planned feature.
+
+# Additional Site Alias Options
+#
+# Aliases are commonly used to define short names for
+# local or remote Drupal installations; however, an alias
+# is really nothing more than a collection of options.
 #
-# - 'uri': The value of --uri should always be the same as
-#   when the site is being accessed from a web browser (e.g. http://example.com)
-# - 'root': The Drupal root; must not be specified as a relative path.
-# - 'host': The fully-qualified domain name of the remote system
-#   hosting the Drupal instance. **Important Note: The remote-host option
-#   must be omitted for local sites, as this option controls various
-#   operations, such as whether or not rsync parameters are for local or
-#   remote machines, and so on.
-# - 'user': The username to log in as when using ssh or rsync.
 # - 'os': The operating system of the remote server.  Valid values
 #   are 'Windows' and 'Linux'. Be sure to set this value for all remote
 #   aliases because the default value is PHP_OS if 'remote-host'
@@ -135,11 +135,14 @@
 #   if you set a 'remote-host' value, and your remote OS is Windows, if you
 #   do not set the 'OS' value, it will default to 'Linux' and could cause
 #   unintended consequences, particularly when running 'drush sql-sync'.
-# - 'ssh': If the target requires special options, such as a non-
-#   standard port, alternative identity file, or alternative
-#   authentication method, the `option` entry under the `ssh` item may
-#   contain a string of extra options that are used with the ssh command,
-#   e.g. "-p 100"
+# - 'ssh': Contains settings used to control how ssh commands are generated
+#   when running remote commands.
+#   - 'options': Contains additional commandline options for the ssh command
+#   itself, e.g. "-p 100"
+#   - 'tty': Usually, Drush will decide whether or not to create a tty (via
+#   the ssh '--t' option) based on whether the local Drush command is running
+#   interactively or not. To force Drush to always or never create a tty,
+#   set the 'ssh.tty' option to 'true' or 'false', respectively.
 # - 'paths': An array of aliases for common rsync targets.
 #   Relative aliases are always taken from the Drupal root.
 #   - 'files': Path to 'files' directory.  This will be looked up if not
@@ -174,15 +177,44 @@
 #         options:
 #           admin-password: 'secret-secret'
 # @endcode
+
+# Site Alias Files for Service Providers
 #
-# Altering aliases:
+# There are a number of service providers that manage Drupal sites as a
+# service. Drush allows service providers to create collections of site alias
+# files to reference all of the sites available to a single user. In order
+# to so this, a new location must be defined in your Drush configuration
+# file:
 #
-# See examples/Commands/SiteAliasAlterCommands.php for an example.
+# @code
+# drush:
+#   paths:
+#     alias-path:
+#       - '${env.home}/.drush/sites/provider-name'
+# @endcode
 #
-# Environment variables:
+# Site aliases stored in this directory may then be referenced by its
+# full alias name, including its location, e.g.:
 #
-# It is no longer possible to set environment variables from within an alias.
-# This is a planned feature.
+#   $ drush @provider-name.example.dev
+#
+# Such alias files may still be referenced by their shorter name, e.g.
+# `@example.dev`. Note that it is necessary to individually list every
+# location where site alias files may be stored; Drush never does recursive
+# (deep) directory searches for alias files.
+#
+# The `site:alias` command may also be used to list all of the sites and
+# environments in a given location, e.g.:
+#
+#   $ drush site:alias @provider-name
+#
+# Add the option `--format=list` to show only the names of each site and
+# environment without also showing the values in each alias record.
+
+# Developer Information
+#
+# See https://github.com/consolidation/site-alias for more developer
+# information about Site Aliases.
 #
 # An example appears below. Edit to suit and remove the @code / @endcode and
 # leading hashes to enable.
@@ -207,4 +239,4 @@
 #   root: /path/to/docroot
 #   uri: https://dev.example.com
 # @endcode
-#
+