Drush Rebuild is a utility for rebuilding a local development environment from, for example, the production environment. Drush Rebuild uses Drush aliases and an easy-to-read YAML configuration file.

To use Rebuild you must know how to work with drush aliases.

Installation & configuration

Installation

Rebuild can be installed with drush or git.

Using drush: drush dl rebuild

Using git: git clone --branch 7.x-1.7 http://git.drupal.org/project/rebuild.git ~/.drush/rebuild

Find the version number on the Rebuild git instructions page.

To test if you installed Rebuild successfully run the command: drush rebuild --version

This should return something like: Drush Rebuild version: 7.x-1.7

Configuration

1. Create a Rebuild YAML configuration file. To do this copy the example config file example.rebuild.yaml from ~/.drush/rebuild/examples to for example the project folder (e.g. at /var/www/drupal-7/rebuild.yaml). Review the copied configuration file as it may contain commands that cannot be run on your site.

2. Add a %rebuild variable to the path-aliases in the drush alias for the site you want to work on. The complete alias could look as follows:

$aliases['example.local'] = array(
    'uri' => 'example.localhost',
    'root' => '/var/www/drupal-7/docroot',
    'path-aliases' => array(
        '%rebuild' => '/var/www/drupal-7/rebuild.yaml',
    ),
);

3. Test rebuilding your local development environment with:
drush rebuild @example.local --source=@example.prod --view-config

Usage

Rebuild

Rebuild your local development environment with the command:
drush rebuild @example.local --source=@example.prod

Display information about past rebuilds

To displays statistics on rebuilds for an environment, run:
drush rebuild-info @example.local

Documentation

Drush Rebuild has documentation available via drush commands:

  • drush help rebuild - Get an overview of available commands and options.
  • drush topic rebuild-readme - Displays the README
  • drush topic rebuild-example - Displays an example rebuild.yml file.

Drush Rebuild: A utility for rebuilding Drupal development environments

Configuration file notes

In general, "1" should be used to denote TRUE and "0" should be used to denote FALSE

The sql_sync, rsync, and site_install sections use the same options as their Drush command counterparts (drush help sql-sync, drush help rsync, drush help site-install, respectively).

Example configuration for rebuilding from a remote environment

This example is valid for cases where you want to rebuild from a remote source (e.g. the production website).

description = "Rebuilds local development environment from remote destination"

The description key lets you add a string that will be displayed to users who rebuild their local environment using the rebuild file. The description is optional.

version: 1.0

The version key lets you specify a version of your info file. Useful for debugging with co-workers.

default_source: @example.prod

Drush Rebuild lets you rebuild your local environment based on any source defined in your drush alias, so you could rebuild based on @staging, @qa, or @production aliases for example. But more often than not, you want your local development environment to match one remote environment. By defining default_source you can save yourself some typing. You'll be able to run drush rebuild @example.local instead of drush rebuild @example.local --source=@example.prod

sql_sync:
  create-db: 'TRUE'
  sanitize: sanitize-email
  structure-tables-key: common

The sql_sync section lets you define options for syncing a remote database to your local environment. If you just wanted database syncing without any additional options, you could write:

sql_sync: 'TRUE'

Note that any option listed in drush help sql-sync can be defined in your rebuild.yml file.

rsync
  files_only: 'TRUE'

As of Drush Rebuild version 1.2, rsync is not fully supported. But the option above (files_only) works just fine. This will rsync the files from your remote environment (what is in sites/default/files) to your local environment. Use with caution for large sites.

In the future, all the options supported by drush rsync will be supported by Drush Rebuild.

variables:
  set:
    preprocess_js: 0
    preprocess_css: 0
    reroute_email_address: '%email'

The variables section is pretty straightforward - use the name of the Drupal variable and assign it a value.

In the code above, note that you can use placeholders that reference values in your Drush alias. This requires a correctly configured Drush alias - see the section above about configuring your alias.

uli: 'TRUE'

If the value is set to 1, Drush Rebuild will open your browser and log you into the site after the rebuild completes successfully. Set to 0, or don't include this in your rebuild.yml file, if you don't want that behavior.

modules:
  enable: 
  - devel
  - devel_node_access
  disable:
  - overlay
  uninstall:
  - comment

Define modules that you want to enable or disable.

  permissions:
    anonymous user:
      grant:
        - access devel information
        - switch users
      revoke:
        - access content

Define permissions that you want to grant or revoke. Make sure you are using the internal permissions name, e.g. for the node module, instead of "View published content", you would specify "access content". When in doubt look at a module's implementation of hook_permission() to find out what value to use.

Granting/revoking permissions is only compatible with Drupal 7 sites at this time.

  drush_scripts:
    pre_process: 'example.php'
    post_process: 'after_rebuild.php'

This section is also straightforward. Note that if your pre_process or post_process script returns FALSE, the rebuild will halt.

overrides: local.rebuild.yml

This is useful when a team is using the same rebuild file. You can define a local overrides file, and exclude it from version control, so that each team member can customize the rebuild process to their liking.

Rebuilding with an install profile

Everything from the above applies except for the sql_sync and rsync sections. In place of that, you will want this:

site_install:
  profile: 'standard'
  account-mail: '%email'
  account-pass: 'admin'
  account-name: 'admin'
  site-name: 'Local install'

Note that the placeholder refers to a value defined in the rebuild section of your Drush alias.