2 # Example of valid statements for an alias file.
4 # To convert legacy alias (*.aliases.drushrc.php) to yml, run the
5 # site:alias-convert command.
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.
13 # Drush site aliases always contain one or more environments;
14 # for example, a site may have "dev", "test" and "live"
15 # environments. The default environment is "dev"; the dev
16 # environment of a site named "example" may therefore be
17 # referred to as either "@example.dev" or "@example".
19 # A canonical alias named "example" that points to a local
20 # Drupal site named "http://example.com" looks like this:
23 # File: example.site.yml
25 # root: /path/to/drupal
26 # uri: http://example.com
29 # Note that the first part of the filename (in this case "example")
30 # defines the name of the site alias, and the top-level key ("dev")
31 # defines the name of the environment.
33 # With this alias definition, then the following commands
36 # $ drush @example.dev status
37 # $ drush --root=/path/to/drupal --uri=http://example.com status
39 # See the --uri option documentation below for hints on setting its value.
41 # Any option that can be placed on the Drush commandline
42 # can also appear in an alias definition inside an 'options' section.
44 # Drush will search for aliases in any of these files using
45 # the alias search path. The following locations are examined
48 # 1. In any path set in drush.alias-path in drush.yml
49 # or (equivalently) any path passed in via --alias-path=...
50 # on the command line.
51 # 2. In one of the site-specific locations:
52 # a. The /drush/sites folder for the current Drupal site
53 # b. The /drush/sites folder in the directory above the current Drupal site
55 # These locations are no longer searched recursively; alias files must
56 # appear directly inside one of the search locations, or it will not be found.
58 # The preferred locations for alias files, then, are:
61 # $ROOT/../drush/sites
63 # If you would like to add additional locations, you can do so by
64 # listing additional locations in your configuration files. For example,
65 # to re-add the default user alias path from Drush 8, put the following
66 # in your ~/.drush/drush.yml configuration file:
72 # - '${env.home}/.drush/sites'
76 # If you run the command `drush core:init`, this configuration will
77 # be done for you automatically.
79 # Files stored in one of the search path locations can be used to create
80 # aliases to local and remote Drupal installations. These aliases can be
81 # used in place of a site specification on the command line, and may also
82 # be used in arguments to certain commands such as "drush rsync" and
85 # To see an example alias definition for the current bootstrapped
86 # site, use the "site:alias" command with the built-in alias "@self":
88 # $ drush site:alias @self
90 # Drush also supports *remote* site aliases. When a site alias is
91 # defined for a remote site, Drush will use the ssh command to run
92 # the requested command on the remote machine. The simplest remote
93 # alias looks like this:
96 # # File: remote.site.yml
98 # host: server.domain.com
100 # root: /other/path/to/drupal
101 # uri: http://example.com
104 # Drush also treats the site alias file /drush/sites/self.site.yml
105 # (in the Drupal root or project root) specially. If your current
106 # working directory is inside a Drupal project, then aliases such
107 # as `@self.live` may be referenced simply as `@live`. Commit the
108 # file self.site.yml to your site's repository to share remote aliases
109 # for a site with team members.
111 # The built-in alias "@none" represents the state of no Drupal site;
112 # to ignore the site at the cwd and just see default drush status:
114 # $ drush @none status
116 # See `drush help site:alias` for more options for displaying site
119 # Although most aliases will contain only a few options, a number
120 # of settings that are commonly used appear below:
122 # - 'uri': The value of --uri should always be the same as
123 # when the site is being accessed from a web browser (e.g. http://example.com)
124 # - 'root': The Drupal root; must not be specified as a relative path.
125 # - 'host': The fully-qualified domain name of the remote system
126 # hosting the Drupal instance. **Important Note: The remote-host option
127 # must be omitted for local sites, as this option controls various
128 # operations, such as whether or not rsync parameters are for local or
129 # remote machines, and so on.
130 # - 'user': The username to log in as when using ssh or rsync.
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': If the target requires special options, such as a non-
139 # standard port, alternative identity file, or alternative
140 # authentication method, the `option` entry under the `ssh` item may
141 # contain a string of extra options that are used with the ssh command,
143 # - 'paths': An array of aliases for common rsync targets.
144 # Relative aliases are always taken from the Drupal root.
145 # - 'files': Path to 'files' directory. This will be looked up if not
147 # - 'drush-script': Path to the remote Drush command.
148 # - 'command': These options will only be set if the alias
149 # is used with the specified command. In the example below, the option
150 # `--no-dump` will be selected whenever the @stage alias
151 # is used in any of the following ways:
152 # - `drush @stage sql-sync @self @live`
153 # - `drush sql-sync @stage @live`
154 # - `drush sql-sync @live @stage`
155 # NOTE: Setting boolean options broke with Symfony 3. This will be fixed
156 # in a future release. See: https://github.com/drush-ops/drush/issues/2956
161 # # File: remote.site.yml
163 # host: server.domain.com
165 # root: /other/path/to/drupal
166 # uri: http://example.com
170 # drush-script: '/path/to/drush'
175 # admin-password: 'secret-secret'
180 # See examples/Commands/SiteAliasAlterCommands.php for an example.
182 # Environment variables:
184 # It is no longer possible to set environment variables from within an alias.
185 # This is a planned feature.
187 # An example appears below. Edit to suit and remove the @code / @endcode and
188 # leading hashes to enable.
191 # # File: mysite.site.yml
193 # uri: http://stage.example.com
194 # root: /path/to/remote/drupal/root
195 # host: mystagingserver.myisp.com
199 # - files: sites/mydrupalsite.com/files
200 # - custom: /my/custom/path
207 # root: /path/to/docroot
208 # uri: https://dev.example.com