Drupal gets really interesting when plugging projects into it. A project can be a module, a theme, an installation profile, or a copy of Drupal core. The task of downloading, extracting, and enabling a project is one of the most common ones while building a site. Fortunately, Drush comes with a set of commands to help us work with modules effectively: the Project Manager commands. Let's start working with them through examples.
pm-releases and pm-releasenotes are very useful tools for inspecting the details of a project prior to downloading it. In the following example, we will use pm-releases to list all available releases for the Freelinking module:
$ drush pm-releases --all freelinking
------- RELEASES FOR 'FREELINKING' PROJECT -------
Release Date Status
7.x-3.x-dev 2011-Sep-02 Development
7.x-3.1 2011-Aug-19 Supported, Recommended
7.x-3.0 2011-Aug-03
The previous command used the option --all to output all the releases and not just the most recent ones. For example, the last one in the list (7.x-3.0) does not have support and is older than 7.x-3.1. The --dev option lists only development releases, as in the following example:
$ drush pm-releases --dev freelinking
------- RELEASES FOR 'FREELINKING' PROJECT -------
Release Date Status
7.x-3.x-dev 2011-Sep-02 Development
If we want to know what is in a project release, we can print its release notes by executing pm-releasenotes. Here is an example of how to print release notes about the latest release of the Freelinking module:
$ drush pm-releasenotes freelinking
----------------------------------------------
> RELEASE NOTES FOR 'FREELINKING' PROJECT, VERSION 7.x-3.1:
> Last updated: August 19, 2011 - 10:51 .
> Supported, Recommended
----------------------------------------------
Official release from tag: 7.x-3.1
* #1247000: Getting freelinking to play nice with Media module
* #959832: Nodetitle rewrites link titles when the target node exists
* #1242090: Warning messages in Feelinking settings
When just the project name is given to pm-releasenotes, the command gathers information about the latest release. A specific version number can be given if needed, as in the following example:
$ drush pm-releasenotes freelinking-7.x-3.0
----------------------------------------------------------
> RELEASE NOTES FOR 'FREELINKING' PROJECT, VERSION 7.x-3.0:
> Last updated: August 3, 2011 - 08:01 .
----------------------------------------------------------
Official release from tag: 7.x-3.0
First stable version of freelinking 3 for Drupal 7.
One of the must-have modules for almost every Drupal website is Views. We are going to download and enable it; but first we will create the directory to place contributed modules according to common good practice regarding module management described at http://drupal.org/documentation/ install/modules-themes/modules-7:
$ cd /home/juampy/projects/drupal
$ mkdir sites/all/modules/contrib
$ drush pm-download views
Project views (7.x-3.0) downloaded to
/home/juampy/projects/drupal/sites/all/modules/contrib/views. [success]
Project views contains 2 modules: views, views_ui.
$ drush pm-enable views views_ui
The following projects have unmet dependencies:
views requires ctools
views_ui requires ctools
Would you like to download them? (y/n):
y
Project ctools (7.x-1.0-rc1) downloaded to
/home/juampy/projects/drupal/sites/all/modules/contrib/ctools.
[success]
Project ctools contains 9 modules: ctools_plugin_example, ctools_ajax_sample, views_content, page_manager, bulk_export, ctools_custom_content, stylizer, ctools_access_ruleset, ctools. The following extensions will be enabled: views, views_ui, ctools
Do you really want to continue? (y/n):
y
ctools was enabled successfully. [ok]
views_ui was enabled successfully. [ok]
views was enabled successfully. [ok]
Views module and its dependencies have been enabled. With just two commands, we did so much:
- Views module was downloaded to
sites/all/modules/contribthrough the commanddrush pm-download views. Drush detected that we had asites/all/modules/contribdirectory (the standard location for contributed modules) and placed the module contents there. - When attempting to enable Views and the Views User Interface modules with
drush pm-enable views views_ui, Drush realized that Views depends on Ctools and asked if we wanted to download it, to which we answered yes (y). Note that Drush can only figure this out when the module name matches with the project name. - CTools was downloaded and before being enabled, Drush prompted asking us for confirmation (we could have appended
--yesat the end of the command to bypass it). We replied yes (y), then hit Enter, and the three modules (views,views_ui, andctools)were enabled in our site.
This task, without using Drush, would have meant to download the correct version of Views from its project page and extract it to sites/all/modules/contrib. Then, download and extract CTools and finally go to the Modules page at admin/modules in our site to enable these two.
Project releases at http://drupal.org follow a naming convention that is used to easily identify the type of support given and maturity, just by reading their name. The structure is [project name]-[Drupal core version]-[project version] (such as views-7.x-3.0). Here is an example that lists all available releases for Views module for Drupal 7. Note that if you are at the root of a Drupal site, you do not need to specify Drupal core version:
$ drush pm-download --select --all views
Choose one of the available releases:
[0] : Cancel
[1] : 7.x-3.x-dev - 2012-Jan-09 - Development
[2] : 7.x-3.0 - 2011-Dec-18 - Supported, Recommended
[3] : 7.x-3.0-rc3 - 2011-Nov-16 - Security
[4] : 7.x-3.0-rc1 - 2011-Jun-17 -
[5] : 7.x-3.0-beta3 - 2011-Mar-28 -
[6] : 7.x-3.0-beta2 - 2011-Mar-26 -
[7] : 7.x-3.0-beta1 - 2011-Mar-26 -
[8] : 7.x-3.0-alpha1 - 2011-Jan-06 -
2
Project views (7.x-3.0) downloaded to /home/juampy/projects/drupal/sites/all/modules/views. [success]
We downloaded views-7.x-3.0. Here is an explanation of each part within the release name:
- Project name is the project unique identifier. This can be found at the URL of the project. In the previous example, the project name is
views. - Drupal core version is the Drupal version that this project supports. Unless a project supports just a specific version of Drupal, this normally is 6.x for Drupal 6 projects and 7.x for Drupal 7 projects.
- The project version is the actual version of the project. In the previous example, it is
3.0.
Drush uses the project release name convention to search for the best release available or lists available releases based on your request. Let's see some examples:
- Download the latest development release of Drupal 8:
$ drush pm-download drupal-8.x
Project drupal (8.x-dev) downloaded to /home/juampy/projects/drupal-8.x-dev. [success]
- Download Drupal 7.7:
$ drush pm-download drupal-7.7
Project drupal (7.7) downloaded to /home/juampy/projects/drupal-7.7. [success]
- Download version 1.3 Organic Groups for my current Drupal site. Note that Drupal core version (for example, 7.x) has not been specified here, so it will be discovered by Drush by inspecting our current path:
$ drush pm-download og-1.3
Project og (7.x-1.3) downloaded to /home/juampy/projects/drupal/sites/all/modules/og. [success]
- Download the latest version of Zen theme for Drupal 6:
$ drush pm-download zen-6.x
Project zen (6.x-2.1) downloaded to /home/juampy/projects/drupal/sites/all/themes/zen. [success]
$ drush pm-download --select --all views
Choose one of the available releases:
[0] : Cancel
[1] : 7.x-3.x-dev - 2012-Jan-09 - Development
[2] : 7.x-3.0 - 2011-Dec-18 - Supported, Recommended
[3] : 7.x-3.0-rc3 - 2011-Nov-16 - Security
[4] : 7.x-3.0-rc1 - 2011-Jun-17 -
[5] : 7.x-3.0-beta3 - 2011-Mar-28 -
[6] : 7.x-3.0-beta2 - 2011-Mar-26 -
[7] : 7.x-3.0-beta1 - 2011-Mar-26 -
[8] : 7.x-3.0-alpha1 - 2011-Jan-06
2
Project views (7.x-3.0) downloaded to /home/juampy/projects/drupal/sites/all/modules/views. [success]
As you can see, there is plenty of flexibility to choose the version you want. However, you normally should not have to worry about it and just provide the project name to pm-download and Drush will do the rest for you.
The Project Manager commands help us to disable and uninstall modules as well. Let's take the chance to review the list of installed modules and do some clean up in order to gain performance in our site:
$ drush pm-list --status=enabled
Package Name Type Version
Chaos tool suite Chaos tools (ctools) Module 7.x-1.0-rc1
Core Block (block) Module 7.10
Core Color (color) Module 7.10
Core Comment (comment) Module 7.10
Core Contextual links (contextual) Module 7.10
...
Core RDF (rdf) Module 7.10
Core User (user) Module 7.10
Views Views (views) Module 7.x-3.0
Core Bartik (bartik) Theme 7.10
Core Seven (seven) Theme 7.10
The RDF module is not needed in this project, so we are going to disable and uninstall it:
$ drush pm-disable --yes rdf
The following extensions will be disabled: rdf
Do you really want to continue? (y/n): y
rdf was disabled successfully. [ok]
$ drush pm-uninstall --yes rdf
The following modules will be uninstalled: rdf
Do you really want to continue? (y/n): y
rdf was successfully uninstalled. [ok]
The previous commands (pm-disable and pm-uninstall) removed the logic (disable) and the data (uninstall) from our site. This saved us from going to the modules list, checking the RDF module, hitting the Save button, and then going to the Uninstall tab and repeating the same task.
At some point you may need to view which version of a module you have installed in a site, where it is located, or view its list of dependencies. The pm-info command extracts extended information about a project within a Drupal site and prints it onscreen. Here is an example where we print detailed information about the Views module:
$ drush pm-info views
Project : views
Type : module
Title : Views
Description : Create customized lists and queries from your database.
Version : 7.x-3.1
Package : Views
Core : 7.x
Status : enabled
Path : sites/all/modules/views
Schema version : 7301
Files : handlers/views_handler_area.inc,
handlers/views_handler_area_result.inc, handlers/views_handler_area_text.inc, handlers/views_handler_area_view.inc, ...
Requires : ctools
Contributed modules are evolving all the time. It won't be long until you see the "There are available updates" alert while navigating through your Drupal site as an administrator. Upgrading a module manually, means the following steps:
- Remove the old version of the module from the source code.
- Download and extract the latest version from the project page and place it where the old version was.
- Open
update.phpin a web browser as the administrator and run database updates, if the new version of the module has any. - Clear the cache.
These steps can be performed with Drush as well. In order to illustrate this, we are going to download and install an early version of the Devel module and then upgrade it to the latest version.
- Download an old version of Devel module. We will ask Drush to list all the available versions for our site and pick one.
$ drush pm-download --select --all devel Choose one of the available releases: [0] : Cancel [1] : 7.x-1.x-dev - 2012-Jan-08 - Development [2] : 7.x-1.2 - 2011-Jul-22 - Supported, Recommended [3] : 7.x-1.1 - 2011-Jul-20 - Security [4] : 7.x-1.0 - 2011-Jan-04 - [5] : 7.x-1.0-rc1 - 2010-Dec-06 - [6] : 7.x-1.0-beta2 - 2010-Apr-21 - [7] : 7.x-1.0-beta1 - 2010-Mar-19 - [8] : 7.x-1.0-alpha1 - 2010-Feb-02 - 8 Project devel (7.x-1.0-alpha1) downloaded to /home/juampy/projects/drupal/sites/all/modules/contrib/devel [success] - Now, we can enable it:
$ drush pm-enable --yes devel The following extensions will be enabled: devel Do you really want to continue? (y/n): y devel was enabled successfully. [ok] - Once enabled, we are going to upgrade it with the
pm-updatecommand. As we do not want Drupal core to be upgraded too, we will add the option--no-coreto it. This command generates a backup for us automatically, in case something goes wrong:drush pm-update --no-core devel Checked available update data for 2 projects. [status] Update information last refreshed: Thu, 01/12/2012 - 02:17 Update status information on all installed and enabled Drupal projects: Name Installed version Proposed version Status Drupal core 7.10 7.10 Up to date Devel 7.x-1.0-alpha1 7.x-1.2 SECURITY UPDATE available Security updates will be made to the following projects: Devel [devel-7.x-1.2] Note: A backup of your project will be stored to backups directory if it is not managed by a supported version control system. Note: If you have made any modifications to any file that belongs to one of these projects, you will have to migrate those modifications after updating. Note: If you have made any modifications to any file that belongs to one of these projects, you will have to migrate those modifications after updating. Do you really want to continue with the update process? (y/n): y Project devel was updated successfully. Installed version is now 7.x-1.2. Backups were saved into the directory /home/juampy/drush-backups/drupal/20120112012028/modules/devel. [ok] Finished performing updates. [ok] The following updates are pending: devel module : 7003 - issue #813132: change schablon.com to white for krumo. Do you wish to run all pending updates? (y/n): y - Done! We have upgraded Devel from version 7.x-1.0-alpha1 to 7.x-1.2. During the process, there was a prompt asking us to confirm the upgrade process and then a backup was made, Devel module got replaced by the latest version and one database update was performed. Now, it would be time to check that our system is working correctly and, if not, we could restore it to its previous status by using the generated backup.