Drush: A zombification remedy

Tags: 

Typical Drupal sites use dozens of modules. Each one is a separate project, with its own programmers working at their own pace. Hardly a month will go by without updates to some of the modules on your site.

Updating modules isn't hard, but it takes time. Worse, it's easy to make mistakes.

Sometimes you need to update Drupal core. Updating core is a bit stressful. You can do major damage to your site if you're not careful.

Drush can help. Drush is software that makes updating Drupal sites easier. When you tell Drush to update a module, it takes care of downloading the right version of the module, copying the files to the right place, and making database changes.

Even better, Drush can update core with a single command. W00f!

You need to use the command line. If that makes you nervous, read this.

Installing Drush

Download Drush to your computer

Start a browser on your PC and grab Drush from http://drupal.org/project/drush. Get the latest stable version. As I'm writing this, it's version 4.4.

You'll get a compressed file, a .zip or .tar.gz, with all the Drush files in it. Extract the files to your computer, as you would with a module or theme.

Upload Drush to your server

You need to upload Drush to your server with FTP, but not where you think you should! Drush is not a module. It doesn't go into sites/all/modules. In fact, it goes outside your Web space entirely! That's important, because you don't want other people running Drush on your site.

Log in to your Web server, using your favorite terminal emulator. I use PuTTY on Windows.

Type cd ~ into PuTTY. This will take you back to your home directory, no matter where you are. For example:

[jsmith@server666 ~/public_html/settings/default]$ cd ~
[jsmith@server666 ~]$

Get a list of the contents of your home directory:

[jsmith@server666 ~]$ ls
logs  mail  public_html  welcome.txt

The directory public_html is the root of your Web site.

Some Web hosts use a different name for this directory.

The files under public_html are accessible over the Web. So if you put the file lassie.html in public_html, everyone can see the file at the URL http://example.com/lassie.html (or whatever your domain is).

Look at this again:

[jsmith@server666 ~]$ ls
logs  mail  public_html  welcome.txt

There's a file called welcome.txt. What's the URL of that file? That's right, there isn't one! Because welcome.txt is outside public_html, it isn't available over the Web.

The lesson: if you want a file to live on your Web server, but not be available over the Web, put it outside public_html. Many people put project documentation and other stuff outside public_html.

Do this from your home directory:

[jsmith@server666 ~]$ mkdir drush
[jsmith@server666 ~]$ ls
drush logs  mail  public_html  welcome.txt

mkdir makes a new directory. The new directory, called drush, is at the same level as public_html. It's not inside public_html. It won't be available on the Web. But you can get to the directory, through SSH (with PuTTY), and through FTP (with your favorite FTP client).

Using FTP, upload the Drush files from your PC to your server, into ~/drush.

Once the files are uploaded, try this:

[jsmith@server666 ~]$ cd ~/drush
[jsmith@server666 ~]$ ls
LICENSE.txt           commands  drush      drush.info
drush_logo-black.png  includes  README.txt docs
drush.bat             drush.php examples

The command cd ~/drush makes ~/drush the current directory. ls shows the files.

If you don't see what you expect, erase the files in cd ~/drush and try again.

Make Drush runnable

You now have Drush on your server. The main Drush program is the file ~/drush/drush, that is, the file drush (no extension) in the directory drush that's a subdirectory of ~, your home directory.

This can make your brain hurt at the beginning, but you'll quickly get used to it.

You want to make Drush act like a shell command, like cd, ls, and mkdir. So that you can type:

[jsmith@server666 ~/public_html]$ drush

and something will happen.

Remember that commands you type are interpreted by Bash, the command shell. You need to do two things:

  • Make the main Drush file executable.
  • Tell Bash where to find it.

Each file has permissions. The permissions affect what Unix will let people do with the file. All operating systems have a permissions system. By default, Unix will not let people execute a file. You need to change that.

Type this:

[jsmith@server666 ~]$ cd ~/drush
[jsmith@server666 ~/drush]$ chmod u+x drush

The command chmod u+x drush says to change permissions of the file drush, making it executable (that's what the x means) by the current user (the u). You are the current user.

You can also change permissions with most FTP clients. I use WinSCP. First, find the file drush, right-click on it, and select Properties:

Figure 1. Making drush runnable - step 1

Now turn on the X (executable) flag for the file's owner (that's you):

Figure 2. Making drush runnable - step 2

Click OK.

drushis now runnable, but you need to tell Bash (the command shell) how to find it. This is easier to do with an FTP client, so I'll just show you that method.

Go to your home directory in the FTP client. That's usually the directory you first see when you connect with FTP. It has public_html in it.

Figure 3. .bashrc in FTP client

You'll see a file called .bashrc. Notice that it's grayed out. Files beginning with . are hidden in Unix. They don't show up with the ls command. The command ls -a will show them; the a means "all."

If the file .bashrc isn't there, create it. In WinSCP, right-click in a blank space in the window, and select New | File. The shortcut is Shift+F4.

.bashrccontains a list of commands that are run when you login to your Unix account. You're going to add an alias.

Edit .bashrc in your FTP client. In WinSCP, right-click on the file and select Edit.

The contents of .bashrc varies across systems. You might see something like this:

# .bashrc
# Source global definitions
if [ -f /etc/bashrc ]; then
. /etc/bashrc
fi

Add this line at the end of the file:

alias drush='~/drush/drush'

This means that whenever you type drush, you really mean ~/drush/drush. That command means "go to the home directory (the ~), then into the drush directory, then run the drush program."

Save the file and close it.

Remember that .bashrc runs when you login. So how do you make it run now? You have two choices:

  • Log out and log in again.
  • Run .bashrc manually, just this once.

To run it manually, type:

[jsmith@server666 ~]$ cd ~
[jsmith@server666 ~]$ source .bashrc

The first command makes sure you're in your home directory. The second tells Bash to run .bashrc.

Time to test it. Switch to the directory containing Drupal. This is usually the root of your site, like public_html:

[jsmith@server666 ~]$ cd ~/public_html
[jsmith@server666 ~/public_html]$ ls
CHANGELOG.txt    LICENSE.txt   includes
profiles         update.php    COPYRIGHT.txt
MAINTAINERS.txt  index.php     robots.txt

(more Drupal files)
[jsmith@server666 ~/public_html]$ drush
Execute a drush command. Run `drush help [command]` to view command-specific help.  Run `drush topic` to read even more documentation.

(more Drushy help)

cd ~/public_html makes the root of your site the current directory.

ls lists the files. Make sure that you see Drupal files there.

drush runs Drush, using the alias you set up in .bashrc.

If you see the Drush help, then - w00f! - you've done it! You've installed Drush. If not, go over the procedures again, and see if you can find a mistake.

It's easier to use Drush than to install it. So, let's go!

Using Drush

Let's see how you use Drush to update modules and themes, and then to update Drupal core. You won't believe how easy it is. But first...

Backup your site

This is optional, but if you choose to, there are two tasks:

  • Backup your Drupal database.
  • Backup your Drupal files.

You want to download copies of your database and files to your PC. If something goes wrong, you can restore.

Web hosting companies usually give you easy-to-use tools for this. For example, cPanel - Hostgator's control panel - has a Backups link under the Files section:

Figure 4. Backups link

Click it, and you'll get a page that lets you backup files and databases:

Figure 5. Backup files and databases

Updating a module or theme

Suppose you go to Drupal's Reports menu and select Available updates. You see this (I rearranged the display to make everything fit):

Figure 6. Update available for the WYSIWYG module

It doesn't matter whether it's a security update or not. It could be a module or a theme. The process is the same.

Here's what you do:

  1. Login with PuTTY.
  2. Go to the directory Drupal is in.
  3. Tell drush to update the module.

When you login, you're at your home directory (~):

[jsmith@server666 ~]$

Let's say Drupal is at the root of your Web site, in ~/public_html (the most common case). Change to that directory:

[jsmith@server666 ~]$ cd ~/public_html
[jsmith@server666 ~/public_html]$

You can confirm that you're in the right place by looking at the files:

[jsmith@server666 ~]$ ls
CHANGELOG.txt    LICENSE.txt    includes
profiles         update.php     COPYRIGHT.txt

MAINTAINERS.txt  index.php      robots.txt
(more Drupal files)

If you want to make sure that Drush is installed, type drush, and you should get some Drush help:

[jsmith@server666 ~/public_html]$ drush
Execute a drush command. Run `drush help [command]` to view command-specific help.  Run `drush topic` to read even more documentation.

(more Drushy help)

OK - now for the big payoff! Here's how you update the WYSIWYG module:

[jsmith@server666 ~]$ drush pm-update wysiwyg

Drush will download the most recent version of the module, backup the old version, and install the new one.

You need to get the name of the module right. With the WYSIWYG module it's easy, but sometimes modules aren't named the way you think. Suppose you saw this update notice:

Figure 7. Another update notice

You might think the right command would be:

[jsmith@server666 ~]$ drush pm-update administration menu

But that's not it. Module names have no spaces in them. At least, their "machine names" don't. A module's machine name is the one used in its URL on Drupal.Org (DO), and the one you need to use for Drush.

So how you do find the machine name? The words "Administration menu" in Figure 7 are a link to the module's home on Drupal.Org. That link's URL contains the machine name of the module. Hover the mouse over the link, and you'll see the URL in your browser's status bar:

Module link

Project URL

Figure 8. Machine name

You can see the module's machine name at the end of the URL: admin_menu. So to update the module:

[jsmith@server666 ~]$ drush pm-update admin_menu

A hint. If you right-click on the module's link, you can copy the URL onto the clipboard:

Copy link location

Figure 9. Copy URL

Then you can paste the URL into PuTTY, and remove the "http://drupal.org/project/" part.

When you paste into PuTTY, don't use Control+V. That means something else to Unix. Use Shift+Insert.

Updating Drupal core

Without Drush, core updates are a headache. Download the new version, uploading the right pieces, making sure you don't lose anything. Stressful stuff.

With Drush, it's easy. Here's the command:

[jsmith@server666 ~]$ drush pm-update drupal

Seriously. That's it. Drush will do all the work.

Conclusion

If you manage a Drupal site, Drush is something you should know. It will make your life easier. This article showed you how to install Drush, and use it to update modules, themes, and core.

Drush can do more than I've covered here. Look at the Drush help (hint: drush | more will break the help text into screen-sized chunks). But updating is the Big Win.