2 # Example of valid statements for an alias file.
4 # Basic Alias File Usage
6 # In its most basic form, the Drush site alias feature provides a way
7 # for teams to share short names that refer to the live and staging sites
8 # (usually remote) for a given Drupal site.
10 # 1. Make a local working clone of your Drupal site and then
11 # `cd` to the project work to select it.
12 # 2. Add an alias file called $PROJECT/drush/sites/self.site.yml,
13 # where $PROJECT is the project root (location of composer.json file).
14 # 3. Run remote commands against the shared live or stage sites
16 # Following these steps, a cache:rebuild on the live environment would be:
18 # $ drush @live cache:rebuild
20 # The site alias file should be named `self.site.yml` because this name is
21 # special, and is used to define the different environments (usually remote)
22 # of the current Drupal site.
24 # The contents of the alias file should look something like the example below:
27 # # File: self.site.yml
29 # host: server.domain.com
31 # root: /other/path/to/live/drupal
32 # uri: http://example.com
34 # host: server.domain.com
36 # root: /other/path/to/stage/drupal
37 # uri: http://stage.example.com
40 # The top-level element names (`live` and `stage` in the example above) are
41 # used to identify the different environments available for this site. These
42 # may be used on the command line to select a different target environment
43 # to operate on by prepending an `@` character, e.g. `@live` or `@stage`.
45 # All of the available aliases for a site's environments may be listed via:
47 # $ drush site:alias @self
49 # The elements of a site alias environment are:
51 # - 'host': The fully-qualified domain name of the remote system
52 # hosting the Drupal instance. **Important Note: The remote-host option
53 # must be omitted for local sites, as this option controls various
54 # operations, such as whether or not rsync parameters are for local or
55 # remote machines, and so on.
56 # - 'user': The username to log in as when using ssh or rsync.
57 # - 'root': The Drupal root; must not be specified as a relative path.
58 # - 'uri': The value of --uri should always be the same as
59 # when the site is being accessed from a web browser (e.g. http://example.com)
61 # Drush uses ssh to run commands on remote systems; all team members should
62 # install ssh keys on the target servers (e.g. via ssh-add).
64 # Advanced Site Alias File Usage
66 # It is also possible to create site alias files that reference other
67 # sites on the same local system. Site alias files for other local sites
68 # are usually stored in the directory `~/.drush/sites`; however, Drush does
69 # not search this location for alias files by default. To use this location,
70 # you must add the path in your Drush configuration file. For example,
71 # to re-add both of the default user alias path from Drush 8, put the following
72 # in your ~/.drush/drush.yml configuration file:
78 # - '${env.home}/.drush/sites'
82 # The command `drush core:init` will automatically configure your
83 # ~/.drush/drush.yml configuration file to add `~/.drush/sites` and
84 # `/etc/drush/sites` as locations where alias files may be placed.
86 # A canonical alias named "example" that points to a local
87 # Drupal site named "http://example.com" looks like this:
90 # File: example.site.yml
92 # root: /path/to/drupal
93 # uri: http://example.com
96 # Note that the first part of the filename (in this case "example")
97 # defines the name of the site alias, and the top-level key ("dev")
98 # defines the name of the environment.
100 # With these definitions in place, it is possible to run commands targeting
101 # the dev environment of the target site via:
103 # $ drush @example.dev status
105 # This command is equivalent to the longer form:
107 # $ drush --root=/path/to/drupal --uri=http://example.com status
109 # See "Additional Site Alias Options" below for more information.
111 # Converting Legacy Alias Files
113 # To convert legacy alias (*.aliases.drushrc.php) to yml, run the
114 # site:alias-convert command.
118 # See examples/Commands/SiteAliasAlterCommands.php for an example.
120 # Environment variables:
122 # It is no longer possible to set environment variables from within an alias.
123 # This is a planned feature.
125 # Additional Site Alias Options
127 # Aliases are commonly used to define short names for
128 # local or remote Drupal installations; however, an alias
129 # is really nothing more than a collection of options.
131 # - 'os': The operating system of the remote server. Valid values
132 # are 'Windows' and 'Linux'. Be sure to set this value for all remote
133 # aliases because the default value is PHP_OS if 'remote-host'
134 # is not set, and 'Linux' (or $options['remote-os']) if it is. Therefore,
135 # if you set a 'remote-host' value, and your remote OS is Windows, if you
136 # do not set the 'OS' value, it will default to 'Linux' and could cause
137 # unintended consequences, particularly when running 'drush sql-sync'.
138 # - 'ssh': Contains settings used to control how ssh commands are generated
139 # when running remote commands.
140 # - 'options': Contains additional commandline options for the ssh command
141 # itself, e.g. "-p 100"
142 # - 'tty': Usually, Drush will decide whether or not to create a tty (via
143 # the ssh '--t' option) based on whether the local Drush command is running
144 # interactively or not. To force Drush to always or never create a tty,
145 # set the 'ssh.tty' option to 'true' or 'false', respectively.
146 # - 'paths': An array of aliases for common rsync targets.
147 # Relative aliases are always taken from the Drupal root.
148 # - 'files': Path to 'files' directory. This will be looked up if not
150 # - 'drush-script': Path to the remote Drush command.
151 # - 'command': These options will only be set if the alias
152 # is used with the specified command. In the example below, the option
153 # `--no-dump` will be selected whenever the @stage alias
154 # is used in any of the following ways:
155 # - `drush @stage sql-sync @self @live`
156 # - `drush sql-sync @stage @live`
157 # - `drush sql-sync @live @stage`
158 # NOTE: Setting boolean options broke with Symfony 3. This will be fixed
159 # in a future release. See: https://github.com/drush-ops/drush/issues/2956
164 # # File: remote.site.yml
166 # host: server.domain.com
168 # root: /other/path/to/drupal
169 # uri: http://example.com
173 # drush-script: '/path/to/drush'
178 # admin-password: 'secret-secret'
181 # Site Alias Files for Service Providers
183 # There are a number of service providers that manage Drupal sites as a
184 # service. Drush allows service providers to create collections of site alias
185 # files to reference all of the sites available to a single user. In order
186 # to so this, a new location must be defined in your Drush configuration
193 # - '${env.home}/.drush/sites/provider-name'
196 # Site aliases stored in this directory may then be referenced by its
197 # full alias name, including its location, e.g.:
199 # $ drush @provider-name.example.dev
201 # Such alias files may still be referenced by their shorter name, e.g.
202 # `@example.dev`. Note that it is necessary to individually list every
203 # location where site alias files may be stored; Drush never does recursive
204 # (deep) directory searches for alias files.
206 # The `site:alias` command may also be used to list all of the sites and
207 # environments in a given location, e.g.:
209 # $ drush site:alias @provider-name
211 # Add the option `--format=list` to show only the names of each site and
212 # environment without also showing the values in each alias record.
214 # Developer Information
216 # See https://github.com/consolidation/site-alias for more developer
217 # information about Site Aliases.
219 # An example appears below. Edit to suit and remove the @code / @endcode and
220 # leading hashes to enable.
223 # # File: mysite.site.yml
225 # uri: http://stage.example.com
226 # root: /path/to/remote/drupal/root
227 # host: mystagingserver.myisp.com
231 # - files: sites/mydrupalsite.com/files
232 # - custom: /my/custom/path
239 # root: /path/to/docroot
240 # uri: https://dev.example.com