# # Example of valid statements for an alias file. # Basic Alias File Usage # # 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. # # 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 # # Following these steps, a cache:rebuild on the live environment would be: # # $ drush @live cache:rebuild # # 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: 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 # # 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`. # # All of the available aliases for a site's environments may be listed via: # # $ drush site:alias @self # # The elements of a site alias environment are: # # - '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. If each user # has to use own username, you can create an environment variable which holds # the value, and reference via ${env.PROJECT_SSH_USER} (for example). Or you may # omit the `user:` item and specify a user in the `~/.ssh/config` file. # - '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) # # 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 # drush: # paths: # alias-path: # - '${env.HOME}/.drush/sites' # - /etc/drush/sites # @endcode # # 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. # # A canonical alias named "example" that points to a local # Drupal site named "http://example.com" looks like this: # # @code # File: example.site.yml # dev: # root: /path/to/drupal # uri: http://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 these definitions in place, it is possible to run commands targeting # the dev environment of the target site via: # # $ drush @example.dev status # # This command is equivalent to the longer form: # # $ 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: # # Site aliases may reference environment variables, just like any Drush config # file. For example, ${env.PROJECT_SSH_USER} will be replaced by the value # of the PROJECT_SSH_USER environment value. # # SSH site aliases may set environment variables via the 'env-vars' key. # See below. # 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. # # - 'docker': When specified, Drush executes via docker-compose exec rather than ssh # - 'service': the name of the container to run on. # - 'exec': # - 'options': Options for the exec subcommand. # - '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' # is not set, and 'Linux' (or $options['remote-os']) if it is. Therefore, # 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': 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 # specified. # - 'drush-script': Path to the remote Drush command. # - 'command': These options will only be set if the alias # is used with the specified command. In the example below, the option # `--no-dump` will be selected whenever the @stage alias # is used in any of the following ways: # - `drush @stage sql-sync @self @live` # - `drush sql-sync @stage @live` # - `drush sql-sync @live @stage` # NOTE: Setting boolean options broke with Symfony 3. This will be fixed # in a future release. See: https://github.com/drush-ops/drush/issues/2956 # - 'env-vars': An array of key / value pairs that will be set as environment # variables. # # Complex example: # # @code # # File: remote.site.yml # live: # host: server.domain.com # user: www-admin # root: /other/path/to/drupal # uri: http://example.com # ssh: # options: '-p 100' # paths: # drush-script: '/path/to/drush' # env-vars: # PATH: /bin:/usr/bin:/home/www-admin/.composer/vendor/bin # DRUPAL_ENV: live # command: # site: # install: # options: # admin-password: 'secret-secret' # @endcode # Site Alias Files for Service Providers # # 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 do this, a new location must be defined in your Drush configuration # file: # # @code # drush: # paths: # alias-path: # - '${env.HOME}/.drush/sites/provider-name' # @endcode # # Site aliases stored in this directory may then be referenced by its # full alias name, including its location, e.g.: # # $ 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. # Wildcard Aliases for Service Providers # # Some service providers that manage Drupal sites allow customers to create # multiple "environments" for a site. It is common for these providers to # also have a feature to automatically create Drush aliases for all of a # user's sites. Rather than write one record for every environment in that # site, it is also possible to write a single "wildcard" alias that represents # all possible environments. This is possible if the contents of each # environment alias are identical save for the name of the environment in # one or more values. The variable `${env-name}` will be substituted with the # environment name wherever it appears. # # Example wildcard record: # # @code # # File: remote-example.site.yml # '*': # host: ${env-name}.server.domain.com # user: www-admin # root: /path/to/${env-name} # uri: http://${env-name}.remote-example.com # @endcode # # With a wildcard record, any environment name may be used, and will always # match. This is not desirable in instances where the specified environment # does not exist (e.g. if the user made a typo). An alias alter hook in a # policy file may be used to catch these mistakes and report an error. # @see SiteAliasAlterCommands for an example on how to do this. # 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. # # @code # # File: mysite.site.yml # local: # This environment is an example of the DockerCompose transport. # docker: # service: drupal # exec: # options: --user USER # stage: # uri: http://stage.example.com # root: /path/to/remote/drupal/root # host: mystagingserver.myisp.com # user: publisher # os: Linux # paths: # - files: sites/mydrupalsite.com/files # - custom: /my/custom/path # command: # sql: # sync: # options: # no-dump: true # dev: # root: /path/to/docroot # uri: https://dev.example.com # @endcode # Example of rsync with exclude-paths # # Note that most options typically passed to rsync via `drush rsync` are # "passthrough options", which is to say they appear after the `--` separator # on the command line. Passthrough options are actually arguments, and # it is not possible to set default arguments in an alias record. The # `drush rsync` command does support two options, `--mode` and `--exclude-paths`, # which are interpreted directly by Drush. Default values for these options # may be specified in an alias record, as shown below. # # @code # dev: # root: /path/to/docroot # uri: https://dev.example.com # command: # core: # rsync: # options: # mode: rlptz # exclude-paths: 'css:imagecache:ctools:js:tmp:php:styles' # @endcode