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.
Drush's main website offers comprehensive lists of all of its commands, for versions 3, 4, and 5.
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.
Theoretically, you can try to install Drush using the tarball on the Drupal.org page.
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.
After the usual welcome screen, you get to choose what components you want in your Drush setup.
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.
Once the two changes have been made to the default installation features, I am ready to continue.
Click the "Install" button.
All of the needed files are unpacked and added to the chosen installation directory.
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.
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.
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.
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".
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.
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.
