5 * Example of valid statements for an alias file.
7 * Use this file as a guide to creating your own aliases.
9 * Aliases are commonly used to define short names for
10 * local or remote Drupal installations; however, an alias
11 * is really nothing more than a collection of options.
12 * A canonical alias named "dev" that points to a local
13 * Drupal site named "http://example.com" looks like this:
16 * $aliases['dev'] = array(
17 * 'root' => '/path/to/drupal',
18 * 'uri' => 'http://example.com',
22 * With this alias definition, then the following commands
26 * $ drush --root=/path/to/drupal --uri=http://example.com status
28 * See the --uri option documentation below for hints on setting its value.
30 * Any option that can be placed on the drush commandline
31 * can also appear in an alias definition.
33 * There are several ways to create alias files.
35 * + Put each alias in a separate file called ALIASNAME.alias.drushrc.php
36 * + Put multiple aliases in a single file called aliases.drushrc.php
37 * + Put groups of aliases into files called GROUPNAME.aliases.drushrc.php
39 * Drush will search for aliases in any of these files using
40 * the alias search path. The following locations are examined
43 * 1. In any path set in $options['alias-path'] in drushrc.php,
44 * or (equivalently) any path passed in via --alias-path=...
45 * on the command line.
46 * 2. In one of the default locations:
49 * 3. In one of the site-specific locations:
50 * a. The /drush and /sites/all/drush folders for the current Drupal site
51 * b. The /drush folder in the directory above the current Drupal site
53 * These locations are searched recursively. If there is a folder called
54 * 'site-aliases' in any search path, then Drush will search for site aliases
55 * only inside that directory.
57 * The preferred locations for alias files, then, are:
59 * /etc/drush/site-aliases
60 * $HOME/.drush/site-aliases
61 * $ROOT/drush/site-aliases
62 * $ROOT/sites/all/drush/site-aliases
63 * $ROOT/../drush/site-aliases
65 * Or any path set in $options['alias-path'] or via --alias-path.
67 * Folders and files containing other versions of drush in their names will
68 * be *skipped* (e.g. mysite.aliases.drush4rc.php or
69 * drush4/mysite.aliases.drushrc.php). Names containing the current version of
70 * Drush (e.g. mysite.aliases.drush5rc.php) will be loaded.
72 * Files stored in these locations can be used to create aliases
73 * to local and remote Drupal installations. These aliases can be
74 * used in place of a site specification on the command line, and
75 * may also be used in arguments to certain commands such as
76 * "drush rsync" and "drush sql-sync".
78 * Alias files that are named after the single alias they contain
79 * may use the syntax for the canonical alias shown at the top of
80 * this file, or they may set values in $options, just
81 * like a drushrc.php configuration file:
84 * $options['uri'] = 'http://example.com';
85 * $options['root'] = '/path/to/drupal';
88 * When alias files use this form, then the name of the alias
89 * is taken from the first part of the alias filename.
91 * Alias groups (aliases stored together in files called
92 * GROUPNAME.aliases.drushrc.php, as mentioned above) also
93 * create an implicit namespace that is named after the group
99 * # File: mysite.aliases.drushrc.php
100 * $aliases['dev'] = array(
101 * 'root' => '/path/to/drupal',
102 * 'uri' => 'http://example.com',
104 * $aliases['live'] = array(
105 * 'root' => '/other/path/to/drupal',
106 * 'uri' => 'http://example.com',
110 * Then the following special aliases are defined:
111 * - @mysite: An alias named after the groupname may be used to reference all of
112 * the aliases in the group (e.g., `drush @mydrupalsite status`).
113 * - @mysite.dev: A copy of @dev.
114 * - @mysite.live: A copy of @live.
116 * Thus, aliases defined in an alias group file may be referred to
117 * either by their simple (short) name, or by their full namespace-qualified
120 * To see an example alias definition for the current bootstrapped
121 * site, use the "site-alias" command with the built-in alias "@self":
123 * $ drush site-alias @self
125 * TIP: If you would like to have drush include a 'databases' record
126 * in the output, include the options --with-db and --show-passwords:
128 * $ drush site-alias @self --with-db --show-passwords
130 * Drush also supports *remote* site aliases. When a site alias is
131 * defined for a remote site, Drush will use the ssh command to run
132 * the requested command on the remote machine. The simplest remote
133 * alias looks like this:
136 * $aliases['live'] = array(
137 * 'remote-host' => 'server.domain.com',
138 * 'remote-user' => 'www-admin',
142 * The form above requires that Drush be installed on the remote machine,
143 * and that there also be an alias of the same name defined on that
144 * machine. The remote alias should define the 'root' and 'uri' elements,
145 * as shown in the initial example at the top of this file.
147 * If you do not wish to maintain site aliases on the remote machine,
148 * then you may define an alias that contains all of the elements
149 * 'remote-host', 'remote-user', 'root' and 'uri'. If you do this, then
150 * Drush will make the remote call using the --root and --uri options
151 * to identify the site, so no site alias is required on the remote server.
154 * $aliases['live'] = array(
155 * 'remote-host' => 'server.domain.com',
156 * 'remote-user' => 'www-admin',
157 * 'root' => '/other/path/to/drupal',
158 * 'uri' => 'http://example.com',
162 * If you would like to see all of the Drupal sites at a specified
163 * root directory, use the built-in alias "@sites":
165 * $ drush -r /path/to/drupal site-alias @sites
167 * It is also possible to define explicit lists of sites using a special
168 * alias list definition. Alias lists contain a list of alias names in
169 * the group, and no other information. For example:
172 * $aliases['mydevsites'] = array(
173 * 'site-list' => array('@mysite.dev', '@otherside.dev')
177 * The built-in alias "@none" represents the state of no Drupal site;
178 * to ignore the site at the cwd and just see default drush status:
180 * $ drush @none status
182 * See `drush help site-alias` for more options for displaying site
183 * aliases. See `drush topic docs-bastion` for instructions on configuring
184 * remote access to a Drupal site behind a firewall via a bastion server.
186 * Although most aliases will contain only a few options, a number
187 * of settings that are commonly used appear below:
189 * - 'uri': In Drupal 7 and 8, the value of --uri should always be the same as
190 * when the site is being accessed from a web browser (e.g. http://example.com)
191 * In Drupal 6, the value of --uri should always be the same as the site's folder
192 * name in the 'sites' folder (e.g. default); it is best if the site folder name
193 * matches the URI from the browser, and is consistent on every instance of the
194 * same site (e.g. also use sites/example.com for http://example.com).
195 * - 'root': The Drupal root; must not be specified as a relative path.
196 * - 'remote-host': The fully-qualified domain name of the remote system
197 * hosting the Drupal instance. **Important Note: The remote-host option
198 * must be omitted for local sites, as this option controls various
199 * operations, such as whether or not rsync parameters are for local or
200 * remote machines, and so on. @see hook_drush_sitealias_alter() in drush.api.php
201 * - 'remote-user': The username to log in as when using ssh or rsync.
202 * - 'os': The operating system of the remote server. Valid values
203 * are 'Windows' and 'Linux'. Be sure to set this value for all remote
204 * aliases because the default value is PHP_OS if 'remote-host'
205 * is not set, and 'Linux' (or $options['remote-os']) if it is. Therefore,
206 * if you set a 'remote-host' value, and your remote OS is Windows, if you
207 * do not set the 'OS' value, it will default to 'Linux' and could cause
208 * unintended consequences, particularly when running 'drush sql-sync'.
209 * - 'ssh-options': If the target requires special options, such as a non-
210 * standard port, alternative identity file, or alternative
211 * authentication method, ssh-options can contain a string of extra
212 * options that are used with the ssh command, eg "-p 100"
213 * - 'parent': Deprecated. See "altering aliases", below.
214 * - 'path-aliases': An array of aliases for common rsync targets.
215 * Relative aliases are always taken from the Drupal root.
216 * - '%drush-script': The path to the 'drush' script, or to 'drush.php'.
217 * This is used by backend invoke when drush
218 * runs a drush command. The default is 'drush' on remote machines, or
219 * the full path to drush.php on the local machine.
220 * - '%drush': A read-only property: points to the folder that the drush
221 * script is stored in.
222 * - '%files': Path to 'files' directory. This will be looked up if not
224 * - '%root': A reference to the Drupal root defined in the 'root' item in the
226 * - 'php': path to custom php interpreter. Windows support limited to Cygwin.
227 * - 'php-options': commandline options for php interpreter, you may
228 * want to set this to '-d error_reporting="E_ALL^E_DEPRECATED"'
229 * - 'variables' : An array of name/value pairs which override Drupal
230 * variables/config. These values take precedence even over settings.php
232 * - 'command-specific': These options will only be set if the alias
233 * is used with the specified command. In the example below, the option
234 * `--no-dump` will be selected whenever the @stage alias
235 * is used in any of the following ways:
236 * - `drush @stage sql-sync @self @live`
237 * - `drush sql-sync @stage @live`
238 * - `drush sql-sync @live @stage`
239 * In case of conflicting options, command-specific options in targets
240 * (source and destination) take precedence over command-specific options
241 * in the bootstrapped site, and command-specific options in a destination
242 * alias will take precedence over those in a source alias.
243 * - 'source-command-specific' and 'target-command-specific': Behaves exactly
244 * like the 'command-specific' option, but is applied only if the alias
245 * is used as the source or target, respectively, of an rsync or sql-sync
246 * command. In the example below, `--skip-tables-list=comments` whenever
247 * the alias @live is the target of an sql-sync command, but comments will
248 * be included if @live is the source for the sql-sync command.
249 * - '#peer': Settings that begin with a '#' are not used directly by Drush, and
250 * in fact are removed before making a backend invoke call (for example).
251 * These kinds of values are useful in conjunction with shell aliases. See
252 * `drush topic docs-shell-aliases` for more information on this.
253 * - '#env-vars': An associative array of keys and values that should be set on
254 * the remote side before invoking drush.
255 * - rsync command options have specific requirements in order to
256 * be passed through by Drush. See the comments on the sample below:
259 * 'command-specific' => array (
260 * 'core-rsync' => array (
262 * // single-letter rsync options are placed in the 'mode' key
263 * // instead of adding '--mode=rultvz' to drush rsync command.
264 * 'mode' => 'rultvz',
266 * // multi-letter rsync options without values must be set to
267 * // TRUE or NULL to work (i.e. setting $VALUE to 1, 0, or ''
271 * // if you need multiple excludes, use an rsync exclude file
272 * 'exclude-from' => "'/etc/rsync/exclude.rules'",
274 * // filter options with white space must be wrapped in "" to preserve
276 * 'filter' => "'exclude *.sql'",
278 * // if you need multple filter options, see rsync merge-file options
279 * 'filter' => "'merge /etc/rsync/default.rules'",
286 * Alias records are written in php, so you may use php code to alter
287 * alias records if you wish. For example:
290 * $common_live = array(
291 * 'remote-host' => 'myserver.isp.com',
292 * 'remote-user' => 'www-admin',
295 * $aliases['live'] = array(
296 * 'uri' => 'http://example.com',
297 * 'root' => '/path.to/root',
301 * If you wish, you might want to put $common_live in a separate file,
302 * and include it at the top of each alias file that uses it.
304 * You may also use a policy file to alter aliases in code as they are
305 * loaded by Drush. See policy_drush_sitealias_alter in
306 * `drush topic docs-policy` for details.
308 * Some examples appear below. Remove the leading hash signs to enable.
311 #$aliases['stage'] = array(
312 # 'uri' => 'http://stage.example.com',
313 # 'root' => '/path/to/remote/drupal/root',
314 # 'remote-host' => 'mystagingserver.myisp.com',
315 # 'remote-user' => 'publisher',
317 # 'path-aliases' => array(
318 # '%drush' => '/path/to/drush',
319 # '%drush-script' => '/path/to/drush/drush',
320 # '%files' => 'sites/mydrupalsite.com/files',
321 # '%custom' => '/my/custom/path',
323 # 'variables' => array(
324 # 'site_name' => 'My Drupal site',
326 # 'command-specific' => array (
327 # 'sql-sync' => array (
331 # # This shell alias will run `mycommand` when executed via
332 # # `drush @stage site-specific-alias`
333 # 'shell-aliases' => array (
334 # 'site-specific-alias' => '!mycommand',
337 #$aliases['dev'] = array(
338 # 'uri' => 'http://dev.example.com',
339 # 'root' => '/path/to/drupal/root',
340 # 'variables' => array(
341 # 'mail_system' => array('default-system' => 'DevelMailLog'),
344 #$aliases['server'] = array(
345 # 'remote-host' => 'mystagingserver.myisp.com',
346 # 'remote-user' => 'publisher',
349 #$aliases['live'] = array(
350 # 'uri' => 'http://example.com',
351 # 'root' => $aliases['dev']['root'],
352 # ) + $aliases['server'];