Drush 5 Installation and Basics for Windows

This article was featured in TheWeeklyDrop, Issue 59, .

In the Drupal community, a growing number of developers are discovering the speed and convenience of creating, configuring, and managing Drupal websites using Drush, a powerful command-line interface (CLI). To the best of my knowledge (i.e., Google!), this is the only Drupal shell currently available.

Drush is not a Drupal module, even though it has a project page. Rather, it is a stand-alone application that can easily work with any Drupal installation. Unpolished versions of it had been created years ago, for Drupal 4 and 5, but the only version currently worth considering is that for Drupal 7. For this article, I will be using the latest version (as of this writing), 7.x-5.7.

Drupal.org page
Figure 1. Drupal.org page

Drush's main website offers comprehensive lists of all of its commands, for versions 3, 4, and 5.

Drush.org
Figure 2. Drush.org

There is a link to the community documentation, but it has a status of "incomplete" at this time. In fact, what little information is available about installing Drush, tends to be geared more toward Linux and Mac OS X. In this article, I will show how to get Drush set up in a Windows environment (in this case, XP), and show the basics of Drush commands, including a couple flaws. Note that version 5 has no fewer than 77 commands, so I will look at only a few of them.

Installation

To get started, first confirm that the target machine is running a supported version of Windows, and it has a command shell listed on the resources page for the Windows installer.

Drush Windows Installer
Figure 3. Drush Windows Installer

Theoretically, you can try to install Drush using the tarball on the Drupal.org page.

Tarball files
Figure 4. Tarball files

But it is much easier to use the Windows MSI installer — in this case, Drush-5.7-2012-08-20-Installer-v1.0.19.msi — which can be downloaded from the link on that resources page.

The process of adding Drush to a Windows machine is fairly straightforward. Start by running the installer file.

Installation welcome
Figure 5. Installation welcome

After the usual welcome screen, you get to choose what components you want in your Drush setup.

Installation default features
Figure 6. Installation default features

The first three components are presumably required, and they are enabled by default. The remaining three components are optional. However, since you are installing Drush on a local web server for managing Drupal sites, and Drupal requires PHP, then you should already have PHP installed. Thus it is not clear why the "Php [sic] Required Runtime" component would be enabled.

By default, Drush is installed in the directory C:\Program Files\Drush\. Most Windows users choose to install all of their applications in the default directory, C:\Program Files\. But using a different directory has the advantage that it distinguishes user-installed programs from those already installed by Windows and those forcibly installed by any application that does not allow one to specify its installation directory. The top-level directory name "_a" (for applications) is short, saving space in the PATH environment variable, and its underscore pushes it to the top of any directory listing sorted alphabetically by filename, thereby making it more visible.

Unfortunately, changing the setting for the PHP runtime component hides the current directory "Location" value and the "Browse…" button for changing it. To redisplay them, you can click the "Next" button, and then the "Back" button in the dialog.

If you prefer a more customized Drush terminal (as do I), then decline to have the Drush environment variables added to your Windows variables for all default command-line terminals (the fifth feature listed). I will show those results presently.

Installation chosen features
Figure 7. Installation chosen features

Once the two changes have been made to the default installation features, I am ready to continue.

Installation ready
Figure 8. Installation ready

Click the "Install" button.

Installation process
Figure 9. Installation process

All of the needed files are unpacked and added to the chosen installation directory.

Installation completed
Figure 10. Installation completed

Drush Terminals

Once the process has finished, the Windows program list (accessible using the Start button), should now contain a "Drush" group, containing two links — one of which is used to start the Drush terminal (incorrectly named the "Drush Command Prompt"), and the second is used for uninstalling Drush.

Drush terminal icon
Figure 11. Drush terminal icon

The Drush terminal is non-optimal, because it starts you in a settings directory, which certainly will not contain any Drupal website upon which you would want to execute Drush commands.

Drush terminal
Figure 12. Drush terminal

Secondly, the shell provided will not contain any of the DOS shell aliases that you use in your development work. Hence it is advisable to instead add the Drush environment variables to whatever shell initialization file you prefer to use, and thus probably end up with a more usable and attractive terminal, with all your aliases available.

Custom terminal
Figure 13. Custom terminal

For the remainder of this article, to illustrate some Drush commands, I will use a fresh installation of Drupal 7, in a directory named "Drupal_7_dev".

D:\_w\Drupal_7_dev :: dir
Volume in drive D is d_1_m
Volume Serial Number is 3818-B713

Directory of D:\_w\Drupal_7_dev

08/24/12  05:02 PM    <DIR>          .
08/24/12  05:02 PM    <DIR>          ..
08/22/12  04:33 PM    <DIR>          includes
08/22/12  04:01 PM    <DIR>          misc
08/22/12  04:01 PM    <DIR>          modules
08/22/12  04:37 PM    <DIR>          profiles
08/22/12  04:01 PM    <DIR>          scripts
08/22/12  04:01 PM    <DIR>          sites
08/22/12  04:01 PM    <DIR>          themes
08/01/12  09:27 AM               174 .gitignore
08/01/12  09:27 AM             5,172 .htaccess
08/01/12  09:27 AM             6,553 authorize.php
08/01/12  09:27 AM               720 cron.php
08/01/12  09:27 AM               529 index.php
08/01/12  09:27 AM               688 install.php
05/02/12  03:10 PM             1,561 robots.txt
08/01/12  09:27 AM            19,416 update.php
08/01/12  09:27 AM             2,051 web.config
9 File(s)         36,864 bytes
9 Dir(s)  88,377,876,480 bytes free

Commands and Options

Any Drush command consists of up to three different types of components: a command, its arguments, and its options. For illustrating the format of Drush commands, I will use the "core-status" command, which provides a lot of useful data about the core of any Drupal installation.

D:\_w\Drupal_7_dev :: drush core-status
Drupal version         :  7.15
Site URI               :  http://default
Database driver        :  mysql
Database hostname      :  localhost
Database username      :  d7_user
Database name          :  d7_dev
Database               :  Connected
Drupal bootstrap       :  Successful
Drupal user            :  Anonymous
Default theme          :  bartik
Administration theme   :  seven
PHP configuration      :  C:\_a\PHP\php.ini
Drush version          :  5.7
Drush configuration    :
Drupal root            :  D:/_w/Drupal_7_dev
Site path              :  sites/default
File directory path    :  sites/default/files
temp                   :  c:\windows\temp

In this example, "drush" is of course the program being run, while "core-status" is the command being passed to Drush. The output consists of multiple pairs of keys and values separated by semicolons.

Drush is able to output the information seen above because it can find the installation's settings file, in this case sites\default\settings.php. But if you are currently no longer in the root directory of a Drupal installation — such as in a directory for temporary files — then Drush can report nothing more than some basic information, independent of any installation.

D:\tmp :: drush core-status
PHP configuration     :  C:\_a\PHP\php.ini
Drush version         :  5.7
Drush configuration   :

It is possible to obtain the status information of a Drupal installation when not currently in its root directory.

D:\tmp :: drush core-status --root=D:\_w\Drupal_7_dev
Drupal version         :  7.15
Site URI               :  http://default
Database driver        :  mysql
Database hostname      :  localhost
Database username      :  d7_user
Database name          :  d7_dev
Database               :  Connected
Drupal bootstrap       :  Successful
Drupal user            :  Anonymous
Default theme          :  bartik
Administration theme   :  seven
PHP configuration      :  C:\_a\PHP\php.ini
Drush version          :  5.7
Drush configuration    :
Drupal root            :  D:\_w\Drupal_7_dev
Site path              :  sites/default
File directory path    :  sites/default/files
temp                   :  c:\windows\temp

This is an excellent example of a command option, "--root", which modifies the behavior of the command.

Command Arguments

The third possible type of element in a command is one or more arguments, which are values passed to the command, similar to arguments passed to PHP functions.

For instance, you can pass an argument of "version" to the core-status command, and it will perform filtering whereby Drush will output only those lines whose keys contain the given argument.

D:\_w\Drupal_7_dev :: drush core-status version
Drupal version   :  7.15
Drush version    :  5.7

Such filtering is case insensitive, i.e., if you use "php" as the filtering argument, it will match any permutation of those three characters, regardless of whether they are uppercase or lowercase.

D:\_w\Drupal_7_dev :: drush core-status php
PHP configuration   :  C:\_a\PHP\php.ini

One might contend that this particular example leaves open the possibility that such filtering is not limited to the keys, nor is case insensitive, because the argument "php" might have matched the "php" in the value part of the key-value pair, "C:\_a\PHP\php.ini", and not the "PHP" in the key part. But if this were the case, then filtering on "ini" would output that same key-value pair, but it does not.

D:\_w\Drupal_7_dev :: drush core-status ini
Administration theme   :  seven

The "ini" does not match "C:\_a\PHP\php.ini", but instead matches "Administration". This demonstrates that only the keys are searched, and that whole-word matching is not required.

Commands can have multiple arguments. For instance, you could filter the status output for both "version" and "database". The output should be some combination of two sets: the keys containing "version", and those containing "database".

D:\_w\Drupal_7_dev :: drush core-status version database
Drupal version      :  7.15
Database driver     :  mysql
Database hostname   :  localhost
Database username   :  d7_user
Database name       :  d7_dev
Database            :  Connected
Drush version       :  5.7

This test demonstrates that the output consists of those pairs whose keys contain at least one of the two arguments (i.e., the union of those two sets), and not the pairs whose keys contain both arguments (i.e., the intersection of the sets).

Command Aliases

Proponents of Drush — or any other CLI — often point out that it is faster to type commands than use a mouse to point-and-click through a GUI consisting of multiple fields sometimes located on multiple pages within an administrative interface. To speed up Drush usage even more, command aliases are available. For example, instead of typing out "core-status", it is sufficient to type "status".

D:\_w\Drupal_7_dev :: drush status
Drupal version         :  7.15
Site URI               :  http://default
Database driver        :  mysql
Database hostname      :  localhost
Database username      :  d7_user
Database name          :  d7_dev
Database               :  Connected
Drupal bootstrap       :  Successful
Drupal user            :  Anonymous
Default theme          :  bartik
Administration theme   :  seven
PHP configuration      :  C:\_a\PHP\php.ini
Drush version          :  5.7
Drush configuration    :
Drupal root            :  D:/_w/Drupal_7_dev
Site path              :  sites/default
File directory path    :  sites/default/files
temp                   :  c:\windows\temp

Commands can have more than one alias.

D:\_w\Drupal_7_dev :: drush st
Drupal version         :  7.15
Site URI               :  http://default
Database driver        :  mysql
Database hostname      :  localhost
Database username      :  d7_user
Database name          :  d7_dev
Database               :  Connected
Drupal bootstrap       :  Successful
Drupal user            :  Anonymous
Default theme          :  bartik
Administration theme   :  seven
PHP configuration      :  C:\_a\PHP\php.ini
Drush version          :  5.7
Drush configuration    :
Drupal root            :  D:/_w/Drupal_7_dev
Site path              :  sites/default
File directory path    :  sites/default/files
temp                   :  c:\windows\temp

One can always learn about these aliases, as well as command arguments and options, by using the "help" command.

D:\_w\Drupal_7_dev :: drush help core-status
Provides a birds-eye view of the current Drupal installation, if any.

Examples:
drush core-status version                 Show all status lines that contain
version information.
drush core-status --pipe                  A list key=value items separated by
line breaks.
drush core-status drush-version --pipe    Emit just the drush version with no
label.

Arguments:
item                                      Optional.  The status item line(s)
to display.

Options:
--full                                    Show all drush aliases in the
report, even if there are a lot.
--show-passwords                          Show database password.

Topics:
docs-readme                               README.txt

Aliases: status, st

Note the two aliases at the bottom of the output.

Command in Action

Let's look at a simple example of modifying a Drupal website's settings from the command line. Say you have a brand new site named "D7 - new site".

Website name before change
Figure 14. Website name before change

Perhaps you decide to change the name to better indicate that it is for development use only.

D:\_w\Drupal_7_dev :: drush variable-set site_name "D7 - dev site"
site_name was set to "D7 - dev site".                                  [success]

Drush always indicates whether a command was successful or not. In this case, it was.

Website name after change
Figure 15. Website name after change

You were able to use the "variable-set" command to modify the website, without even having to login as an administrator.

Gotchas

Drush was most likely developed in a Linux environment, and thus it is no surprise that there are some blemishes that may be limited to usage on Windows machines. For instance, the "pm-download" command is a real-time-saver for downloading Drupal core, modules, and themes.

D:\tmp :: drush pm-download drupal

Destination directory                                                    [error]
C:\DOCUME~1\User\LOCALS~1\Temp/drush_tmp_1349890664_5075b268be991/drupal-7.15
already exists.
Project drupal (7.15) downloaded to D:/tmp/drupal-7.15.                [success]
Project drupal contains:                                               [success]
- 3 profiles: testing, standard, minimal
- 4 themes: stark, seven, garland, bartik
- 47 modules: drupal_system_listing_incompatible_test,
drupal_system_listing_compatible_test, user, update, trigger,
translation, tracker, toolbar, taxonomy, system, syslog, statistics,
simpletest, shortcut, search, rdf, profile, poll, php, path, overlay,
openid, node, menu, locale, image, help, forum, filter, file,
field_ui, text, options, number, list, field_sql_storage, field,
dblog, dashboard, contextual, contact, comment, color, book, blog,
block, aggregator

The "--drupal-project-rename" option of the "pm-download" command is handy for setting the name of a Drupal installation to something other than the default, "drupal-7.15", at the same time that one downloads the installation file from Drupal.org. But it does not work on Windows. (This problem is a known issue.)

D:\tmp :: drush pm-download drupal --drupal-project-rename=new

Source directory                                                         [error]
C:\DOCUME~1\User\LOCALS~1\Temp/drush_tmp_1349890538_5075b1ea68957/x
drupal-7.15 is not readable or does not exist.
copy(C:\DOCUME~1\User\LOCALS~1\Temp/drush_tmp_1349890538_5075b1ea68957/new):
[warning]
failed to open stream: No such file or directory filesystem.inc:229
Project drupal (7.15) could not be downloaded to D:/tmp/new.             [error]

A workaround is to perform the installation, which uses the default name, and then change the directory to a new name. After that, one can create the Drupal database using the "site-install" command. In this example, I am opting for the "standard" installation profile.

D:\tmp :: dir
Directory of D:\tmp
10/10/12  11:33 AM    <DIR>          .
10/10/12  11:33 AM    <DIR>          ..
10/10/12  11:20 AM    <DIR>          drupal-7.15

D:\tmp :: ren drupal-7.15 new

D:\tmp :: cd new

D:\tmp\new :: drush site-install --db-url=mysql://root:pass@localhost/new
--site-name=New standard

You are about to CREATE  the 'new' database. Do you want to continue? (y/n)
: y
Starting Drupal installation. This takes a few seconds ...                  [ok]
Installation complete.  User name: admin  User password: 5DXqx3Aasb         [ok]

Drush informs us of the username and (randomly generated) password of the superuser. I am now ready to begin working with a complete installation of Drupal 7.

Despite the potential pitfalls awaiting Windows users, all Drupal developers who have not yet tried Drush are encouraged to do so, as they will likely discover the value of creating and managing websites from the command line.

Copyright © 2012 Michael J. Ross. All rights reserved.
bad bots block