Drush User's Guide

Debian and Ubuntu users can easily install php-cli with the following command:

$ sudo apt-get install php5-cli

Once the installation completes, verify the installed version with php -v.

Mac users have php-cli installed by default but need to make it available from anywhere in the terminal. The whereis command helps to find where a command is located. The following command shows how the whereis command is used to find where a command is located, if we have the PHP binary in our system:

$ whereis -b php
php: /usr/bin/php /usr/share/php /usr/share/man/man1/php.1.gz

If the command has found any results, as in the previous example, try executing them appending -v to see if the version is 5.2 or higher. If you have found it, create a symbolic link that points to any of the paths listed within your PATH environment variable. Now, in the future you can just type php instead of the full path where it's located. We will first print the available paths and then create a symbolic link to one of them:

$ echo $PATH
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin: /usr/games:/home/juampy/local/bin:/opt/android-sdk-linux_x86/tools
$ sudo ln -s /path/to/php/executable /usr/local/bin/php

After that, you should be able to run php -v without errors.

Drush has a Windows installer that sets up everything you need to start using Drush. The process is very similar to installing any other software in Windows.

Here are the steps to get it working:

C:\> php -v C:\> drush

The alternative installation method requires knowledge of the Windows system variables configuration and administrative permissions to replace a Windows library. The result has Drush 5 installed and works as the automatic installer does.

Installing required libraries

Drush needs a few libraries to be installed in order to work correctly. Take into account the following tips prior to installing them:

• Each installer can be found in their home pages at the first setup link of the Download section.

• When you open an installer, you may see up to three security warnings, as shown in the following screenshot, before the installation starts. Accept them, as these libraries should not involve any risk for your system.

• During the installation process, leave all options with their default values and accept the terms of use.

Here are the home pages of each of the libraries:

• http://gnuwin32.sourceforge.net/packages/libarchive.htm

• http://gnuwin32.sourceforge.net/packages/gzip.htm

• http://gnuwin32.sourceforge.net/packages/wget.htm

• http://gnuwin32.sourceforge.net/packages/gtar.htm

Replacing the TAR Library

Now, we will replace the Windows Tar library (tar) with the one we just installed, by performing the following steps:

1. 1. Open the file explorer and browse to the folder C:\Program Files\GnuWin32\bin\.

2. 2. Rename the file tar to tar_default. If Windows asks you to confirm this operation, accept it.

3. 3. Make a copy of the file bsdtar (located in the same directory) and rename the copy to tar. If you can see the file extensions, keep them.

4. 4. Your bin folder should look as shown in the following screenshot, after doing this.

Installing Drush

In a web browser, open the Drush Project page and download the zip package of the All-versions-5.x-dev release: http://drupal.org/project/drush.

Extract the contents of the zip file to the root of your C drive, so drush.bat can be reached at C:\drush\drush.bat.

Configure environment variables

Configure your Path system variable by going to My Computer | Properties | Advanced System Settings | Environment Variables. At the System Variables list, double-click on Path and append this at the end of the Variable value field: ;C:\php;C:\drush;C:\Program Files\GnuWin32\bin.

As you can see, we are providing the Path variable with the location of the PHP, Drush, and libraries directories. Make sure that these paths are correct as in some installations they may vary (for example, WAMP installs PHP at C:\wamp\bin\php and some Windows versions have Program Files (x86) instead of Program Files). Save the value and close all the windows you opened for doing this.

C:\> drush core-status
PHP configuration : C:\php\php.ini Drush version : 5.0-dev Drush configuration : Drush alias files :

If you use the default php.ini configuration file, you may encounter unexpected errors using Drush such as timeouts, errors not being shown, or functions not being found. This is because the default configuration of PHP is too restrictive. Therefore, we will first identify where it is and if is not shared with the web server, configure it. If it is, an alternative method to override some of its settings will be explained.

You can easily find the php.ini file being used by Drush with the core-status command:

$ drush core-status PHP
PHP configuration : /etc/php5/cli/php.ini

Now, in order to find out if the web server uses this file, create a file called info.php in a directory visible by your web server:

<?php
phpinfo():

Now open it in a web browser and look for the line Loaded Configuration File:

If the file path is different from the one that drush core-status PHP reported, you are safe to go ahead configuring it. If not, create a php.ini file within the Drush installation directory (for example, at /home/juampy/drush/php.ini) with the following contents:

memory_limit = 128M
error_reporting = E_ALL | E_NOTICE | E_STRICT
display_errors = stderr
safe_mode =
open_basedir =
disable_functions =
disable_classes =

These settings make sure that Drush has enough memory to run; errors are printed onscreen and some PHP variables do not restrict it.

Let's start with a very simple command such as core-status, which prints configuration information about Drush and, if applicable, a Drupal site. If executed at the root of a Drupal directory with its database configured at sites/default/settings.php, the following command would return:

$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

This output is informing us the main configuration of our site and Drush, which is its default behavior. Now, we can print its help information to find out that it can actually do more than that:

$ drush help core-status 
Provides a birds-eye view of the current Drupal installation, if any.
Examples: drush status version 	Show all status lines that 
					contain version information.
drush status --pipe 			A list key=value items 
					separatedby line breaks.
drush status drush-version--pipe 	Emit just the drush version 
					with no label.
Arguments: item 			Optional. The status item 
					line(s) to display.
Options: --show-passwords 		Show database password.
Topics: 
   docs-readme 				README.txt
Aliases: status, st

As we can see, the core-status command accepts arguments and options when being called. We will now see how to use them.

An argument is a piece of information that acts as input data for a command. They are typed next to the command name and separated by spaces.

The help information of the core-status command (type drush help core-status to see it again) says that we can specify the items which we want it to print. Therefore, if we need to print just the items containing version in the item name, we could do the following:

$ drush core-status version Drupal version : 7.10 
Drush version : 4.5

You can try and change version by something else or even add more parameters after it, so the command will print items containing them as well. If we wanted version and database information to be printed, the following command would do it:

$ drush core-status version database 
Drupal version : 7.10 
Database driver : mysql 
Database hostname : localhost 
Database username : root 
Database name : drupal7db 
Database : Connected 
Drush version : 4.5

You can give any number of arguments to a command. Beware that some commands expect the arguments to be given in a certain order. For example, the command variable-set expects that the variable name to be set is the first argument and its new value is the second argument.

Hence, the following example sets the variable site-name with the value My Drupal site:

$ drush variable-set site_name "My Drupal site"

Drush commands accept options, which modify their default behavior. If, for example, we wanted to list the database connection details of a Drupal site, we would do the following:

$ cd /path/to/drupal/root/ 
$ drush core-status --show-passwords database
Database driver : mysql 
Database hostname : localhost 
Database username : root 
Database name : drupal7site 
Database password : drupal7sitePassword 
Database : Connected

The option --show-passwords is telling Drush that we want to see the database password of the site where we currently are. This option is needed because, by default, the status command does not show database passwords.

Here is a full command that prints version and database information with database passwords in a key=value format. Its full syntax is detailed as follows:

$ drush core-status --show-passwords --pipe version database 
	command      options                               arguments

As you can see, options are given after the command name and arguments are given at the end. You can actually change the order and even mix them, but for clarity we will follow the given structure.

In order to read the description and available arguments and options for a command, use drush help and append to it the command name as an argument, such as:

$ drush help core-status

In the previous example, core-status is not a command but an argument for the help command telling it that we want to see help information about the core-status command.

Most of the Drush options have a short and long format and they may accept a value too. You can see if an option has a short format in the command help. As an example, if we wanted to tell a Drush command the URL of our site, we could do it in two ways. Here is the short one:

$ drush cache-clear -l drupal7.localhost all

And this is the long one:

$ drush cache-clear --uri=drupal7.localhost all

In this book, we will use the long format as it makes clearer the difference between option values from arguments.

There are some options which are applicable to most Drush commands. You can see a list of these using the following command:

$ drush topic core-global-options

Most of the Drush commands have a shorter alias to help us type less. You can see them between parenthesis next to each command name. Therefore, the following command $ drush status is a shortcut for $ drush core-status.

For clarity, we will not use command aliases in this book, but you should learn and use them. Here is an example showing a portion of the help information of the core-status command where its aliases are listed in parenthesis.

$ drush help core-status
 ... core-status (status, st) Provides a birds-eye view of the current Drupal 
 installation, if any 
 ...

This means that the three following commands give the same result:

$ drush core-status 
$ drush status 
$ drush st

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.