Drupal: A beginner's guide to Drush

See more about:

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!

Drush is great, but it makes newcomers nervous. One problem is that Drush is a command line program. That is, you run it by typing commands, like this:

Using Drush

Figure 1. Running Drush

This scares some people. Too geeky by far. 

Don't worry. It's true that you can damage your site at the command line. But that's also true when you use FTP. I'll walk you through the process of installing and using Drush. I'll show you how to be safe.

Is this your first time using the Unix command line? This article is for you.

I'll assume that you've installed Drupal a few times, know how to use FTP, and know how to use your hosting provider's control panel. The control panel is the software they give you to manage your Web site. cPanel is a common one.

What "the command line" is

It's important that you know what someone means when they say "the command line." Let's see how this compares with what you're used to.

Copying a file - the GUI way

You're using a computer right now. If you aren't, pretend you are. This is you:

You and a computer

Figure 2. You and a computer

Suppose you're copying a file, a drawing of a bug. Your screen might look like this:

Copying a file

Figure 3. Copying a file

You hold down the control key, and drag the file to the window on the right.

These actions are called "gestures." They're things people do to control computers. Typing on a keyboard, moving a mouse or a trackball, pressing a button on a game controller, they're all gestures.

To copy the bug file, a program on your computer had to interpret your gesture (control+dragging), and do some computerish action (copy a file). What program is that? It's Windows Explorer (WE). (Or whatever you use on your computer of choice.)

Note that Windows and Windows Explorer (WE) are different. Windows is the operating system. WE is a program that runs on a Windows computer.

Here's what happens when you copy a file:

File copying process

Figure 4. File copying process

  • You click and drag.
  • WE watches you, and figures out that you want to copy a file.
  • WE sends some commands to Windows.
  • Windows sends some commands to the disk drive (actually, the software drivers that control the drive).
  • The disk drive sends a response back to Windows, confirming that everything went OK.
  • Windows sends a response to WE.
  • WE updates the screen, showing you the new state of your computer:

File copied

Figure 5. File copied

Where is this happening?

You, the computer, WE, Windows, the hard disk, and the computer's screen are all in the same place.

This is the most common case. I'll ignore X Windows and other things.

When you copy a file, many thousands - if not millions - of pixels change. Here's Figure 2 again:

Copying a file

Figure 2 (again). Copying a file

As you drag the bug, you see a copy of the bug (or an outline) changing position as you move the mouse. That's thousands of pixels that need to change. When you let go of the mouse button, the window on the right is redrawn, showing that there's a new file in town.

Drawing all those pixels is not a problem for your computer. It has a fast CPU, a fast video card, a fast disk, and fast connections between them. It can move thousands of bits in a fraction of a second, without raising a sweat.

Now, how does this compare to the command line?

Copying a file - the command line way

When you use the command line, you're usually working on a computer that's far away. Right now, I'm in Michigan, USA. The CoreDogs Web server is in Texas, USA. It's over 1,000 miles away.

The server is just a computer. It has the same types of components as any computer, but the software is different.

Different software

Figure 6. Different software

My PC runs the Windows operating system. The Web server runs Unix (or a variant). My PC has Windows Explorer for letting me mess with files. The Web server has Bash for letting me mess with files. Bash is a "command shell." It knows how to interpret your commands and tell the OS what to do.

Here's the Windows file copy process again:

File copying process

Figure 4 (again). File copying process

It looks the same with Unix:

Figure 7. Copying files in Unix

Here's the important difference:

Far away

Figure 8. Far away

I'm in Michigan, typing, gesturing away. The computer doing what I tell it is in Texas. My gestures have to travel over 1,000 miles before they can be interpreted.

There's another problem as well. The reason shared hosting is so cheap is that many people use the same Unix computer, at the same time:

Many remote users

Figure 9. Many remote users

Using a GUI is not practical. Making changes to many GUI screens at once would overload the server. Sending the bazillons of bits for those screens would make things slow for users.

The solution is to:

  • Limit the input, the gestures people can make. Get rid of the mouse. Keyboard only. Key codes are small and fast.
  • Limit the output, the computer's responses to the gestures. No pictures, no icons, no sound (except for a beep). Only text. Text codes are small and fast.

When you can only use keyboard input and text output, the way you work changes a lot. It's generally more difficult.

How do you copy a file? There are no windows. No icons. Nothing to drag and drop. Nothing to drag and drop with.

Because using the command line is more difficult, you only use it when there's a very good reason. Drush is one of those reasons. It's quicker to use command-line Drush to update a module, than it is to do it in the normal drag-and-drop FTP way.

Connecting

How do you get to your server's command line? The first thing to know is that sometimes you can't. Some Web hosting companies refuse to give you access.

Avoid those companies. Do business with a company that will give you "shell access" to your server. That refers to a command shell like Bash, that interprets your keyboard-only gestures.

All my accounts are with Hostgator; I've used them for years. They give you shell access, but you need to ask for it. Use the online chat support.

You can buy a Hostgator account by clicking here:

Buy hosting

If you buy hosting using this link, CoreDogs gets a referral fee.

So you have shell access. Now you need to run a program on your computer that can connect. Most Windows users use PuTTY, a free tool. It will send your guestures (keystrokes only) to the remote computer, and show its responses (text only).

Download PuTTY. You'll get a single .exe file. It's not an installation program, it's the entire tool. Run it.

Hint: You might want to create a directory like C:\Program files\PuTTY, put putty.exe in there, and make a shortcut to it on your Start menu.

PuTTY will show you a configuration screen. The most important piece is this:

Starting PuTTY

Figure 10. Starting PuTTY

Type in your connection address, which is usually the same as your Web site's URL, without the http:// part. So if your site is at http://example.com, you would type:

Connecting

Figure 11. Connecting

Use SSH as the connection type. It encrypts everything, including the username and password that you're about to enter.

22 is the standard SSH port. Almost all hosting companies use that. Hostgator uses 2222 instead for its shared hosting plans:

Hostgator SSH port

Figure 12. Hostgator SSH port

You could just hit the Open button at this point, but I recommend making one more change. Click on "Colours" in the left window:

PuTTY colors

Figure 13. PuTTY colors

Then select "Use system colours":

Use system colours

Figure 14. Use system colours

This will make text easier to see.

Now click on the Open button to open a connection. You might see a message about a new key, if this is the first time you've used PuTTY with your server. The key is part of the encryption system used to protect your data as it goes flying about the Internet. Go ahead and tell PuTTY that the key is OK.

Next you'll see a login screen:

Login

Figure 15. Login

The prompt ("login as:" etc.) comes from your server. If you see that, congrats! You've got some text from the server! W00f!

Login with the username and password associated with your account. It's usually the same info you use to login to your FTP account, when you upload things.

Next you'll see something like this:

[jsmith@server666 ~]$

This is the "command prompt." It tells you some useful things.

jsmith is the username, that you typed when logging in. server666 is the name of the server. Hosting companies have lots of servers. This is the name of your server, within their server herd. The $ is server-speak for "I'm ready."

The ~ (tilde, pronounced TIL-da) is important. It's your current directory. The concept of a "current directory" doesn't come up for most GUI users, so this idea takes getting used to.

In Windows, you have directories and subdirectories (or folders and subfolders, same thing). It's the same in Unix. There are directories with subdirectories, and so on.

Type ls and press Enter. ls is the command to list file names. You'll see something like this:

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

This is the contents of a directory. But which directory? There are thousands of directories on a typical server. Which directory has these four items?

The answer: the current directory. You can change the current directory up and down the directory tree. The same command - ls - shows you the contents of the current directory, whatever it is. Some examples in a moment.

What about that ~? That's Unix-speak for your home directory. Every Unix user has his/her own home directory. When you log in through PuTTY, that's where you start.

The command prompt usually tells you what the current directory is. Here's the first one again:

[jsmith@server666 ~]$

The ~ says "you are in your home directory."

Here's that ls command again:

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

These are the things in the home directory. The first three are subdirectories. The last one is a file. PuTTY might color-code them for you, depending on how things are set up.

public_html is a subdirectory of ~. It's actually the root of your Web site. So if someone types http://example.com/fetch.html in their browser, your server will send them the file ~/public_html/fetch.html

IMPORTANT! Not all servers are organized this way, though most I've seen are. YMMV.

Type cd public_html and press Enter:

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

cd is the command "change directory."

Look at the new command prompt. It's telling you that the current directory is now ~/public_html. So if you type ls, you'll see the files in that directory:

[jsmith@server666 ~/public_html]$ ls
CHANGELOG.txt    LICENSE.txt    includes

profiles         update.php     COPYRIGHT.txt
MAINTAINERS.txt  index.php      robots.txt

(more)

These are Drupal files.

Try this: type cd .. and press Enter. Then send the ls command:

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

logs  mail  public_html  welcome.txt

cd .. says to "go up one level." The prompt changes to ~, and ls shows you the files in the current directory, your home directory.

If you get lost in your directory tree, this:

[jsmith@server666 ~]$cd ~

will always take you back to your home directory.

To sum up:

  • Commands like ls show you what's in the current directory.
  • You can change the current directory with the cd command.
  • If you get lost, cd ~ will take you to your home directory.

W00f! You're getting your geek on now!

Installing Drush

That's (almost) all you need to know about the command line to work with Drush. Let's install it.

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

Now upload Drush to your server, 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.

Type cd ~ into PuTTY. Remember, 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

Remember that the directory public_html is the root of your Web site. 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 16. Making drush runnable - step 1

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

Making drush runnable - step 2

Figure 17. Making drush runnable - step 2

Click OK.

drush is 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.

.barshrc in FTP client

Figure 18. .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.

.bashrc contains 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

There are two things to do:

  • 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:

Backups link

Figure 19. Backups link

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

Backup files and databases

Figure 20. 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):

Update notice

Figure 21. 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. You could be using Drupal 6 or Drupal 7. 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:

Another update notice

Figure 22. 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, and the one you need to use for Drush.

So how you do find the machine name? The words "Administration menu" in Figure 22 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 23. 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 24. 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.

Comment on this article if you have questions, or spot errors. If there's something you don't understand, tell me, and I might be able to improve the explanation.

Drush Errors - Drush command terminated abnormally...

First, thank you for this tutorial! It is one of the most clearly written and easy to understand tutorials on Drush that I can find and I have spent hours digging!

I followed all of the instructions above but I am still not able to get drush to function for my site(s). I can enter the $ drush command and see that it is installed and get help, etc. but when I try to update a module, I get the following error:

Error: Cannot redeclare system_help() (previously declared in /home1/durangp4/public_html/modules/system/system.module:46) in /home1/durangp4/public_html/modules/modules/system/system.module, line 105

Also, when I have looked at other tutorials, some point to the command $ drush status and when I run that, I get a very short string that makes me think I have not connected them correctly - as follows:

durangp4@durangotherapist.com [~]# drush status
PHP configuration : /etc/php.ini
Drush version : 4.5
Drush configuration :
Drush alias files :

I have 2 sites on this hosting account, the primary "durangocounseling.com" which is the main site inside of the public_html directory and I have a subdirectory that has another add on site.

I have looked all over and cant find any similar issues or documentation. Any help you have would be greatly appreciated!

Found theCulprit

First, I found that I needed to try to run updates in the folder that I needed to update. That is, I had my main site located in the public_html folder but also had another site located in a subdirectory - e.g. public_html/site2. So I had to go to the public_html directory to update those modules: e.g. cd ~/public_html.

The second main issue was that I found I had, at some point, accidentally created a duplicate modules folder (e.g. modules/modules/...) That folder was being referenced in my systems table in my database so i had to first get rid of the duplicate folder that was confusing Drush, then manually delete all instances in the system table of any references to module/module/...

Then I ran update.php, cleared all caches and I was finally able to watch the magic of Drush unfold! Thank you again for a great help and you have converted yet another Drush believer....


How to...

Lessons

User login

Log in problems? Try here


Dogs