Some Drush commands are to be executed on a non-Drupal directory (for example, site-install), others behave differently when executed on a Drupal directory (such as pm-download), and the remaining ones must be called within or referencing a Drupal directory (sql-connect). Here, we will explain how to tell Drush explicitly or implicitly that we want it to work with a Drupal site in particular.
Drush gathers information from arguments, options, and configuration files, creating a context.
The recommended method for working with Drush, against a Drupal site, is to run all commands from the root path of the site (where the index.php file is). This means that if, for example, a Drupal site is installed at /var/www/drupal7/ and its settings file is located at /var/www/drupal7/sites/default/settings.php, you could clear the cache by doing the following:
$ cd /var/www/drupal7/ $
drush cache-clear
The previous command will work correctly because Drush realizes that we are at the root of a Drupal directory and will find a database configuration at sites/default/settings.php. However, if we were using the multi-site feature of Drupal, settings.php would not be at sites/default, but at something such as sites/drupal7.localhost. In this scenario, we can still run commands easily by placing ourselves at the same level of the settings.php. This means the following commands:
$ cd /var/www/drupal7/sites/drupal7.localhost $ drush cache-clear
This command works because Drush finds a settings.php file right where we are. If we would have tried to clear the cache from the root path (/var/www/drupal7/) as in the previous example, Drush would have printed an error:
$ cd /var/www/drupal7 $ drush cache-clear
The drush command 'cache-clear' could not be executed. [error] Could not find a Drupal settings.php file at ./sites/default/settings.php. [error]
This command fails because Drush looks for /var/www/drupal7/sites/default/settings.php with no success. It does not have a database to clear its cache, and hence fails. To overcome this, we can make use of explicit methods to help Drush find our site, as explained in the next section.
Note
If you do not know how the Drupal multi-site feature works, read about it at http://drupal.org/documentation/install/multi-site.
By informing Drush where the root path is and the site name within sites subdirectory, we can execute commands from any directory. For example, if our Drupal root path is located at /var/www/drupal7 and the settings.php is in a different directory than sites/default (which happens on multi-site installations), then we could invoke the command from the Drupal root path specifying the site name as an option:
$ cd /var/www/drupal7 $ drush cache-clear --uri=drupal7.localhost
We can even go one step further and clear the cache of our Drupal site without even being at the root path by running the following commands:
$ cd /home/juampy $ drush cache-clear --root=/var/www/drupal7 --uri=drupal7.localhost
This command is saying "Hey Drush, I want you to clear the cache of a Drupal site which has its root path at /var/www/drupal7 and its settings.php at /var /www/drupal7/sites/drupal7.localhost".
Whenever you want to check the current active context, you can make use of the core-status command. See the following example, where it is executed in a non-Drupal directory:
$ cd /home/juampy $ drush core-status
PHP configuration : /etc/php5/apache2/php.ini Drush version : 4.5 Drush configuration : Drush alias files :
You can see that Drush just prints its version info and the location of the loaded php.ini configuration file. Now, we are going to run drush core-status from the root of a Drupal directory with its settings.php file located at sites/default:
$ cd /home/juampy/myDrupalSite
$ drush core-status
Drupal version : 7.4
Site URI : http://drupal7.localhost
Database driver : mysql
Database hostname : localhost
Database username : root
Database name : drupal7
Database : Connected
Drupal bootstrap : Successful
Drupal user : Anonymous
Default theme : bartik
Administration theme : seven
PHP configuration : /etc/php5/apache2/php.ini
Drush version : 4.5
Drush configuration :
Drush alias files :
Drupal root : /home/juampy/myDrupalSite Site
path : sites/default
File directory path : sites/default/files
As you can see in the previous example, Drush discovers the site and prints its configuration details.
Drush incorporates a killer feature to provide all the information needed to run a command against a Drupal site from any directory with just one parameter (for example, drush @mysite core-status). It is called Drush site alias and it is explained in Chapter 3, Customizing Drush. There is another way of doing this which is with Drush configuration files, which will be explained as well.