first import

sites/all/modules/drush/examples/example.aliases.drushrc.php

@@ -0,0 +1,210 @@
+<?php
+
+/**
+ * Example of valid statements for an alias file.  Use this
+ * file as a guide to creating your own aliases.
+ *
+ * Aliases are commonly used to define short names for
+ * local or remote Drupal installations; however, an alias
+ * is really nothing more than a collection of options.
+ * A canonical alias named "dev" that points to a local
+ * Drupal site named "dev.mydrupalsite.com" looks like this: 
+ *
+ *   $aliases['dev'] = array(
+ *     'root' => '/path/to/drupal',
+ *     'uri' => 'dev.mydrupalsite.com',
+ *   );
+ *
+ * With this alias definition, then the following commands
+ * are equivalent:
+ *
+ *   $ drush @dev status
+ *   $ drush --root=/path/to/drupal --uri=dev.mydrupalsite.com status
+ *
+ * Any option that can be placed on the drush commandline
+ * can also appear in an alias definition.
+ *
+ * There are several ways to create alias files.
+ *
+ *   + Put each alias in a separate file called ALIASNAME.alias.drushrc.php
+ *   + Put multiple aliases in a single file called aliases.drushrc.php
+ *   + Put groups of aliases into files called GROUPNAME.aliases.drushrc.php
+ *
+ * Drush will search for aliases in any of these files using
+ * the alias search path.  The following locations are examined
+ * for alias files:
+ *
+ *   1. In any path set in $options['alias-path'] in drushrc.php,
+ *      or (equivalently) any path passed in via --alias-path=...
+ *      on the command line.
+ *   2. If 'alias-path' is not set, then in one of the default
+ *      locations:
+ *        a. /etc/drush
+ *        b. In the drush installation folder
+ *        c. Inside the 'aliases' folder in the drush installation folder
+ *        d. $HOME/.drush
+ *   3. Inside the sites folder of any bootstrapped Drupal site,
+ *      or any local Drupal site indicated by an alias used as
+ *      a parameter to a command
+ *
+ * Files stored in these locations can be used to create aliases
+ * to local and remote Drupal installations.  These aliases can be
+ * used in place of a site specification on the command line, and
+ * may also be used in arguments to certain commands such as
+ * "drush rsync" and "drush sql-sync".
+ *
+ * Alias files that are named after the single alias they contain
+ * may use the syntax for the canoncial alias shown at the top of
+ * this file, or they may set values in $options, just
+ * like a drushrc.php configuration file:
+ *
+ *   $options['uri'] = 'dev.mydrupalsite.com',
+ *   $options['root'] = '/path/to/drupal';
+ *
+ * When alias files use this form, then the name of the alias
+ * is taken from the first part of the alias filename.
+ *
+ * Alias groups (aliases stored together in files called 
+ * GROUPNAME.aliases.drushrc.php, as mentioned above) also
+ * create an implicit namespace that is named after the group
+ * name.  
+ *
+ * For example:
+ *
+ *   # File: mysite.aliases.drushrc.php
+ *   $aliases['dev'] = array(
+ *     'root' => '/path/to/drupal',
+ *     'uri' => 'dev.mydrupalsite.com',
+ *   );
+ *   $aliases['live'] = array(
+ *     'root' => '/other/path/to/drupal',
+ *     'uri' => 'mydrupalsite.com',
+ *   );
+ *
+ * Then the following special aliases are defined:
+ *
+ *   @mysite            An alias named after the groupname
+ *                      may be used to reference all of the
+ *                      aliases in the group (e.g. drush @mydrupalsite status)
+ *
+ *   @mysite.dev        A copy of @dev
+ *
+ *   @mysite.live       A copy of @live
+ *
+ * Thus, aliases defined in an alias group file may be referred to
+ * either by their simple (short) name, or by thier full namespace-qualified
+ * name.
+ *
+ * To see an example alias definition for the current bootstrapped
+ * site, use the "site-alias" command with the built-in alias "@self":
+ *
+ *   $ drush site-alias @self
+ *
+ * If you would like to see all of the Drupal sites at a specified
+ * root directory, use the built-in alias "@sites":
+ *
+ *   $ drush -r /path/to/drupal site-alias @sites
+ *
+ * See 'drush help site-alias' for more options for displaying site
+ * aliases.
+ *
+ * Although most aliases will contain only a few options, a number
+ * of settings that are commonly used appear below:
+ *
+ * - 'uri': This should always be the same as the site's folder name
+ *     in the 'sites' folder.
+ * - 'root': The Drupal root; must not be specified as a relative path.
+ * - 'remote-port': If the database is remote and 'db-url' contains
+ *     a tunneled port number, put the actual database port number
+ *     used on the remote machine in the 'remote-port' setting.
+ * - 'remote-host': The fully-qualified domain name of the remote system
+ *     hosting the Drupal instance.  The remote-host option must be
+ *     omitted for local sites, as this option controls whether or not
+ *     rsync parameters are for local or remote machines.
+ * - 'remote-user': The username to log in as when using ssh or rsync.
+ * - 'ssh-options': If the target requires special options, such as a non-
+ *     standard port, alternative identity file, or alternative
+ *     authentication method, ssh- options can contain a string of extra
+ *     options that are used with the ssh command, eg "-p 100"
+ * - 'parent': The name of a parent alias (e.g. '@server') to use as a basis
+ *     for this alias.  Any value of the parent will appear in the child
+ *     unless overridden by an item with the same name in the child.
+ *     Multiple inheritance is possible; name multiple parents in the
+ *     'parent' item separated by commas (e.g. '@server,@devsite').
+ * - 'db-url': The Drupal 6 database connection string from settings.php.
+ *     For remote databases accessed via an ssh tunnel, set the port
+ *     number to the tunneled port as it is accessed on the local machine.
+ *     If 'db-url' is not provided, then drush will automatically look it
+ *     up, either from settings.php on the local machine, or via backend invoke
+ *     if the target alias specifies a remote server.
+ * - 'databases': Like 'db-url', but contains the full Drupal 7 databases
+ *     record.  Drush will look up the 'databases' record if it is not specified.
+ * - 'path-aliases': An array of aliases for common rsync targets.
+ *   Relative aliases are always taken from the Drupal root.
+ *     '%drush-script': The path to the 'drush' script, or to 'drush.php' or
+ *       'drush.bat', as desired.  This is used by backend invoke when drush
+ *       runs a drush command.  The default is 'drush' on remote machines, or 
+ *       the full path to drush.php on the local machine.
+ *     '%drush': A read-only property: points to the folder that the drush script
+ *       is stored in.
+ *     '%dump-dir': Path to directory that "drush sql-sync" should use to store
+ *       sql-dump files. Helpful filenames are auto-generated.
+ *     '%dump': Path to the file that "drush sql-sync" should use to store sql-dump file.
+ *     '%files': Path to 'files' directory.  This will be looked up if not specified.
+ *     '%root': A reference to the Drupal root defined in the 'root' item
+ *       in the site alias record.
+ * - 'command-specific': These options will only be set if the alias
+ *   is used with the specified command.  In the example below, the option
+ *   `--no-cache` will be selected whenever the @stage alias
+ *   is used in any of the following ways:
+ *      drush @stage sql-sync @self @live
+ *      drush sql-sync @stage @live
+ *      drush sql-sync @live @stage
+ *   In case of conflicting options, command-specific options in targets
+ *   (source and destination) take precedence over command-specific options
+ *   in the bootstrapped site, and command-specific options in a destination
+ *   alias will take precedence over those in a source alias.
+ * - 'source-command-specific' and 'target-command-specific': Behaves exactly
+ *   like the 'command-specific' option, but is applied only if the alias
+ *   is used as the source or target, respectively, of an rsync or sql-sync
+ *   command.  In the example below, `--skip-tables-list=comments` whenever
+ *   the alias @live is the target of an sql-sync command, but comments will
+ *   be included if @live is the source for the sql-sync command.
+ * Some examples appear below.  Remove the leading hash signs to enable.
+ */
+#$aliases['stage'] = array(
+#    'uri' => 'stage.mydrupalsite.com',
+#    'root' => '/path/to/remote/drupal/root',
+#    'db-url' => 'pgsql://username:password@dbhost.com:port/databasename',
+#    'remote-host' => 'mystagingserver.myisp.com',
+#    'remote-user' => 'publisher',
+#    'path-aliases' => array(
+#      '%drush' => '/path/to/drush',
+#      '%drush-script' => '/path/to/drush/drush',
+#      '%dump-dir' => '/path/to/dumps/',
+#      '%files' => 'sites/mydrupalsite.com/files',
+#      '%custom' => '/my/custom/path',
+#     ),
+#     'command-specific' => array (
+#       'sql-sync' => array (
+#         'no-cache' => TRUE,
+#       ),
+#     ),
+#  );
+#$aliases['dev'] = array(
+#    'uri' => 'dev.mydrupalsite.com',
+#    'root' => '/path/to/drupal/root',
+#  );
+#$aliases['server'] = array(
+#    'remote-host' => 'mystagingserver.myisp.com',
+#    'remote-user' => 'publisher',
+#  );
+#$aliases['live'] = array(
+#    'parent' => '@server,@dev',
+#    'uri' => 'mydrupalsite.com',
+#     'target-command-specific' => array (
+#       'sql-sync' => array (
+#         'skip-tables-list' => 'comments',
+#       ),
+#     ),
+#  );

sites/all/modules/drush/examples/example.bashrc

@@ -0,0 +1,20 @@
+# Examples of valid statements for a drush bashrc file. Use this file to cut down on
+# typing of options and avoid mistakes.
+#
+# Rename this file to .bashrc and optionally copy it to one of
+# four convenient places:
+#
+# 1. User's $HOME folder (i.e. ~/.bashrc).
+# 2. User's .drush folder (i.e. ~/.drush/.bashrc).
+# 3. System wide configuration folder (e.g. /etc/drush/.bashrc).
+# 4. System wide command folder (e.g. /usr/share/drush/command/.bashrc).
+# 5. Drush installation folder
+#
+# Drush will search for .bashrc files whenever the drush interactive
+# shell, i.e. `drush core-cli` is entered.   If a configuration file 
+# is found in any of the above locations, it will be sourced by bash 
+# and merged with other configuration files encountered.
+
+alias siwef='site-install wef --account-name=super --account-mail=me@wef'
+alias dump='sql-dump --structure-tables-key=wef --ordered-dump'
+alias cli-update='(drush core-cli --pipe > $HOME/.bash_aliases) && source $HOME/.bash_aliases'

sites/all/modules/drush/examples/example.drush.ini

@@ -0,0 +1,70 @@
+;
+; Example of a drush php settings override file
+;
+; IMPORTANT:  Before following the instructions in
+; this file, first check to see that the cli version
+; of php is installed on your system.  (e.g. On
+; debian systems, `sudo apt-get install php5-cli`.)
+;
+; Use this file in instances when your system is
+; -not- configured to use separate php.ini files for
+; webserver and cli use.  You can determine which
+; php.ini file drush is using by running "drush status".
+; If the php.ini file shown is your webserver ini
+; file, then rename this file, example.drush.ini,
+; to drush.ini and copy it to one of the following 
+; locations:
+;
+; 1. Drush installation folder
+; 2. User's .drush folder (i.e. ~/.drush/drush.ini)
+; 3. System wide configuration folder (i.e. /etc/drush/drush.ini)
+;
+; When in use, the variables defined in this file
+; will override the setting values that appear in
+; your php.ini file.  See the examples below for
+; some values that may need to be set in order for
+; drush to work.
+;
+; NOTE:  There is a certain amount of overhead
+; required for each override, so drush.ini should
+; only be used for a relatively small number
+; of variables.  Comment out any variable that
+; has the same value as the webserver php.ini
+; to keep the size of the override list small.
+;
+; To fully specify the value of all php.ini variables, 
+; copy your webserver php.ini file to one of the 
+; locations mentioned above (e.g. /etc/drush/php.ini)
+; and edit it to suit.
+;
+; The options listed below are particularly relevant
+; to drush.
+; 
+
+;
+; drush needs as much memory as Drupal in order
+; to run; make the memory limit setting match
+; what you have in your webserver's php.ini.
+;
+memory_limit = 128M
+
+;
+; Show all errors and direct them to stderr
+; when running drush.
+;
+error_reporting = E_ALL | E_NOTICE | E_STRICT
+display_errors = stderr
+
+;
+; If your php.ini for your webserver is too
+; restrictive, you can re-enable functionality
+; for drush by adjusting values in this file.
+;
+; Here are some examples of settings that are
+; sometimes set to restrictive values in a
+; webserver's php.ini:
+;
+;safe_mode = 
+;open_basedir = 
+;disable_functions =
+;disable_classes =

sites/all/modules/drush/examples/example.drushrc.php

@@ -0,0 +1,230 @@
+<?php
+
+/*
+ * Examples of valid statements for a drushrc.php file. Use this file to cut down on
+ * typing of options and avoid mistakes.
+ *
+ * Rename this file to drushrc.php and optionally copy it to one of
+ * five convenient places, listed below in order of precedence:
+ *
+ * 1. Drupal site folder (e.g sites/{default|example.com}/drushrc.php).
+ * 2. Drupal installation root.
+ * 3. In any location, as specified by the --config (-c) option.
+ * 4. User's .drush folder (i.e. ~/.drush/drushrc.php).
+ * 5. System wide configuration folder (e.g. /etc/drush/drushrc.php).
+ * 6. Drush installation folder.
+ *
+ * If a configuration file is found in any of the above locations, it
+ * will be loaded and merged with other configuration files in the
+ * search list.
+ *
+ * IMPORTANT NOTE on configuration file loading:
+ *
+ * At its core, drush works by "bootstrapping" the Drupal environment
+ * in very much the same way that is done during a normal page request
+ * from the web server, so most drush commands run in the context
+ * of a fully-initialized website.
+ *
+ * Configuration files are loaded in the reverse order they are
+ * shown above.  Configuration files #6 through #3 are loaded immediately;
+ * the configuration file stored in the Drupal root is loaded
+ * when Drupal is initialized, and the configuration file stored
+ * in the site folder is loaded when the site is initialized.
+ *
+ * This load order means that in a multi-site environment, the
+ * configuration file stored in the site folder will only be
+ * available for commands that operate on that one particular
+ * site.  Additionally, there are some drush commands such as
+ * pm-download do not bootstrap a drupal environment at all,
+ * and therefore only have access to configuration files #6 - #3.
+ * The drush commands 'rsync' and 'sql-sync' are special cases.
+ * These commands will load the configuration file for the site
+ * specified by the source parameter; however, they do not
+ * load the configuration file for the site specified by the
+ * destination parameter, nor do they load configuration files
+ * for remote sites.
+ *
+ * See `drush topic docs-bootstrap` for more information on how
+ * bootstrapping affects the loading of drush configuration files.
+ */
+
+// Specify a particular multisite.
+# $options['l'] = 'http://example.com/subir';
+
+// Specify your Drupal core base directory (useful if you use symlinks).
+# $options['r'] = '/home/USER/workspace/drupal-6';
+
+// Load a drushrc.php configuration file from the current working directory.
+# $options['c'] = '.';
+
+// You should not use drush-4.x on Windows; upgrade to the 5.x branch.
+// If you are really sure that you want to ignore this advice, you may
+// still disable the warning by setting the 'check_os' setting to the
+// special value shown below.
+# $options['check_os'] = 'i-want-4.x';
+
+// Control automatically check for updates in pm-updatecode and drush version.
+// FALSE = never check for updates.  'head' = allow updates to drush-HEAD.
+// TRUE (default) = allow updates to latest stable release.
+# $options['self-update'] = FALSE;
+
+// By default, drush will download projects compatibile with the
+// current version of Drupal, or, if no Drupal site is specified,
+// then the Drupal-7 version of the project is downloaded.  Set
+// default-major to select a different default version.
+# $options['default-major'] = 6;
+
+// Specify CVS for checkouts
+# $options['package-handler'] = 'cvs';
+
+// Specify CVS credentials for checkouts (requires --package-handler=cvs)
+# $options['cvscredentials'] = 'name:password';
+
+// Specify additional directories to search for *.drush.inc files
+// Separate by : (Unix-based systems) or ; (Windows).
+# $options['i'] = 'sites/default:profiles/myprofile';
+
+// Specify additional directories to search for *.alias.drushrc.php
+// and *.aliases.drushrc.php files
+# $options['alias-path'] = '/path/to/aliases:/path2/to/more/aliases';
+
+// Specify directory where sql-sync will store persistent dump files.
+// Keeping the dump files around will improve the performance of rsync
+// when the database is rsync'ed to a remote system.  If a dump directory
+// is not specified, then sql-sync will store dumps in temporary files.
+# $options['dump-dir'] = '/path/to/dumpdir';
+
+// Specify directory where sql-dump should store backups of database
+// dumps.  @DATABASE is replaced with the name of the database being
+// dumped, and @DATE is replaced with the current time and date of the
+// dump.  TRUE will cause sql-dump to use the same backup directory that
+// pm-updatecode does.
+//
+// If set, this can be explicitly overridden by specifying --result-file
+// on the commandline.  The default behavior of dumping to
+// STDOUT can be achieved via --result-file=0
+# $options['result-file'] = '/path/to/backup/dir/@DATABASE_@DATE.sql';
+# $options['result-file'] = TRUE;
+
+// Enable verbose mode.
+# $options['v'] = 1;
+
+// Show database passwords in 'status' and 'sql-conf' commands
+# $options['show-passwords'] = 1;
+
+// Default logging level for php notices.  Defaults to "notice"; set to "warning"
+// if doing drush development.  Also make sure that error_reporting is set to E_ALL
+// in your php configuration file.  See 'drush status' for the path to your php.ini file.
+# $options['php-notices'] = 'warning';
+
+// Specify options to pass to ssh in backend invoke. (Default is to prohibit password authentication; uncomment to change)
+# $options['ssh-options'] = '-o PasswordAuthentication=no';
+
+// rsync version 2.6.8 or earlier will give an error message:
+// "--remove-source-files: unknown option".  To fix this, set
+// $options['rsync-version'] = '2.6.8'; (replace with the lowest
+// version of rsync installed on any system you are using with
+// drush).  Note that drush requires at least rsync version 2.6.4
+// for some functions to work correctly.
+// 
+// Note that this option can also be set in a site alias.  This
+// is preferable if newer versions of rsync are available on some
+// of the systems you use.
+// See: http://drupal.org/node/955092
+# $options['rsync-version'] = '2.6.9';
+
+/*
+* The output charset suitable to pass to iconv PHP function as out_charset
+* parameter. Drush will convert its output from UTF-8 to the charset specified
+* here. It is possible to use //TRANSLIT and //IGNORE charset name suffixes
+* (see iconv documentation). If not defined conversion will not be performed.
+*/
+# $options['output_charset'] = 'ISO-8859-1';
+# $options['output_charset'] = 'KOI8-R//IGNORE';
+# $options['output_charset'] = 'ISO-8859-1//TRANSLIT';
+
+/*
+ * Multiple command execution options
+ */
+// By default, drush will prepend the name of the
+// site to the output of any multiple-site command 
+// execution.  To disable this behavior, set the
+// --no-label option
+# $options['no-label'] = TRUE;
+
+/*
+ * Customize this associative array with your own tables. This is the list of
+ * tables whose *data* is skipped by the 'sql-dump' and 'sql-sync' commands when
+ * a structure-tables-key is provided. You may add new tables to the existing
+ * array or add a new element.
+ */
+$options['structure-tables'] = array(
+ 'common' => array('cache', 'cache_filter', 'cache_menu', 'cache_page', 'history', 'sessions', 'watchdog'),
+);
+
+/*
+ * Customize this associative array with your own tables. This is the list of
+ * tables that are entirely omitted by the 'sql-dump' and 'sql-sync' commands
+ * when a skip-tables-key is provided. This is useful if your database contains
+ * non Drupal tables used by some other application or during a migration for
+ * example. You may add new tables to the existing array or add a new element.
+ */
+$options['skip-tables'] = array(
+ 'common' => array('migration_data1', 'migration_data2'),
+);
+
+/*
+ * Command-specific options
+ *
+ * To define options that are only applicable to certain commands,
+ * make an entry in the 'command-specific' structures as shown below.
+ * The name of the command may be either the command's full name
+ * or any of the command's aliases.
+ *
+ * Options defined here will be overridden by options of the same
+ * name on the command line.  Unary flags such as "--verbose" are overridden
+ * via special "--no-xxx" options (e.g. "--no-verbose").
+ *
+ * Limitation: If 'verbose' is set in a command-specific option,
+ * it must be cleared by '--no-verbose', not '--no-v', and visa-versa.
+ */
+# $command_specific['rsync'] = array('verbose' => TRUE);
+# $command_specific['dl'] = array('cvscredentials' => 'user:pass');
+
+// Specify additional directories to search for scripts
+// Separate by : (Unix-based systems) or ; (Windows).
+# $command_specific['script']['script-path'] = 'sites/all/scripts:profiles/myprofile/scripts';
+
+// Always show release notes when running pm-update or pm-updatecode
+# $command_specific['pm-update'] = array('notes' => TRUE);
+# $command_specific['pm-updatecode'] = array('notes' => TRUE);
+
+// List of drush commands or aliases that should override built-in 
+// shell functions and commands; otherwise, built-ins override drush 
+// commands. Default is help,dd,sa.
+// Warning:  bad things can happen if you put the wrong thing here
+// (e.g. eval, grep), so be cautious.
+// If a drush command overrides a built-in command (e.g. bash help),
+// then you can use the `builtin` operator to run the built-in version
+// (e.g. `builtin help` to show bash help instead of drush help.)
+// If a drush command overrides a shell command (e.g. grep), then
+// you can use the regular shell command by typing in the full path
+// to the command (e.g. /bin/grep).
+# $command_specific['core-cli'] = array('override' => 'help,dd,sa');
+
+/**
+ * Variable overrides:
+ *
+ * To override specific entries in the 'variable' table for this site,
+ * set them here. Any configuration setting from the 'variable'
+ * table can be given a new value. We use the $override global here
+ * to make sure that changes from settings.php can not wipe out these
+ * settings.
+ *
+ * Remove the leading hash signs to enable.
+ */
+# $override = array(
+#   'site_name' => 'My Drupal site',
+#   'theme_default' => 'minnelli',
+#   'anonymous' => 'Visitor',
+# );

sites/all/modules/drush/examples/helloworld.script

@@ -0,0 +1,50 @@
+#!/usr/bin/env drush
+
+//
+// This example demonstrates how to write a drush
+// "shebang" script.  These scripts start with the
+// line "#!/usr/bin/env drush" or "#!/full/path/to/drush".
+//
+// See `drush topic docs-scripts` for more information.
+//
+drush_print("Hello world!");
+drush_print();
+drush_print("The arguments to this command were:");
+
+//
+// If called with --everything, use drush_get_arguments
+// to print the commandline arguments.  Note that this
+// call will include 'php-script' (the drush command)
+// and the path to this script.
+//
+if (drush_get_option('everything')) {
+  drush_print("  " . implode("\n  ", drush_get_arguments()));
+}
+//
+// If --everything is not included, then use
+// drush_shift to pull off the arguments one at
+// a time.  drush_shift only returns the user
+// commandline arguments, and does not include
+// the drush command or the path to this script.
+//
+else {
+  while ($arg = drush_shift()) {
+    drush_print('  ' . $arg);
+  }
+}
+
+drush_print();
+
+//
+// We can check which site was bootstrapped via
+// the '@self' alias, which is defined only if
+// there is a bootstrapped site.
+//
+$self_record = drush_sitealias_get_record('@self');
+if (empty($self_record)) {
+  drush_print('No bootstrapped site.');
+}
+else {
+  drush_print('The following site is bootstrapped:');
+  _drush_sitealias_print_record($self_record);
+}

sites/all/modules/drush/examples/policy.drush.inc

@@ -0,0 +1,58 @@
+<?php
+
+/**
+ * @file
+ *   Example policy commandfile. Modify as desired.
+ *
+ *   Validates commands as they are issued and returns an error 
+ *   or changes options when policy is violated.
+ *
+ *   You can copy this file to any of the following
+ *     1. A .drush folder in your HOME folder.
+ *     2. Anywhere in a folder tree below an active module on your site.
+ *     3. /usr/share/drush/commands (configurable)
+ *     4. In an arbitrary folder specified with the --include option.
+ */
+
+/**
+ * Implement of drush_hook_COMMAND_validate().
+ * 
+ * Prevent catastrophic braino. Note that this file has to be local to the machine
+ * that intitiates sql-sync command.
+ */
+function drush_policy_sql_sync_validate($source = NULL, $destination = NULL) {
+  if ($destination == '@prod') {
+    return drush_set_error(dt('Per examples/policy.drush.inc, you may never overwrite the production database.'));
+  }
+}
+
+/**
+ * Implement of drush_hook_COMMAND_validate().
+ *
+ * To test this example without copying, execute `drush --include=./examples updatedb`
+ * from within your drush directory.
+ * 
+ * Unauthorized users may view pending updates but not execute them.
+ */
+function drush_policy_updatedb_validate() {
+  // Check for a token in the request. In this case, we require --token=secret.
+  if (!drush_get_option('token') == 'secret') {
+    drush_log(dt('Per site policy, you must add a secret --token complete this command. See examples/policy.drush.inc.  If you are running a version of drush prior to 4.3 and are not sure why you are seeing this message, please see http://drupal.org/node/1024824.'), 'warning');
+    drush_set_context('DRUSH_AFFIRMATIVE', FALSE);
+    drush_set_context('DRUSH_NEGATIVE', TRUE);
+  }
+}
+
+/**
+ * Implementation of drush_hook_COMMAND_validate().
+ * 
+ * Only sudo tells me to make a sandwich: http://xkcd.com/149/
+ */
+function drush_policy_make_me_a_sandwich_validate() {
+  $name = posix_getpwuid(posix_geteuid());
+  if ($name['name'] !== 'root') {
+    return drush_set_error('MAKE_IT_YOUSELF', dt('What? Make your own sandwich.'));
+  }
+}
+
+

sites/all/modules/drush/examples/sandwich-topic.txt

@@ -0,0 +1,4 @@
+I have discovered a truly marvelous proof that it is impossible to 
+separate a sandwich into two cubes, or four sandwiches into two
+fourth of a sandwich, or in general, any sandwich larger than the 
+second into two like sandwiches. This text file is too narrow to contain it.

sites/all/modules/drush/examples/sandwich.drush.inc

@@ -0,0 +1,161 @@
+<?php
+
+/**
+ * @file
+ *   Example drush command.
+ *
+ *   To run this *fun* command, execute `sudo drush --include=./examples mmas`
+ *   from within your drush directory.
+ *
+ *   See `drush topic docs-commands` for more information about command authoring. 
+ *
+ *   You can copy this file to any of the following
+ *     1. A .drush folder in your HOME folder.
+ *     2. Anywhere in a folder tree below an active module on your site.
+ *     3. /usr/share/drush/commands (configurable)
+ *     4. In an arbitrary folder specified with the --include option.
+ */
+
+/**
+ * Implementation of hook_drush_command().
+ *
+ * In this hook, you specify which commands your
+ * drush module makes available, what it does and
+ * description.
+ *
+ * Notice how this structure closely resembles how
+ * you define menu hooks.
+ *
+ * See `drush topic docs-commands` for a list of recognized keys.
+ *
+ * @return
+ *   An associative array describing your command(s).
+ */
+function sandwich_drush_command() {
+  $items = array();
+
+  // The 'make-me-a-sandwich' command
+  $items['make-me-a-sandwich'] = array(
+    'description' => "Makes a delicious sandwich.",
+    'arguments' => array(
+      'filling' => 'The type of the sandwich (turkey, cheese, etc.)',
+    ),
+    'options' => array(
+      'spreads' => 'Comma delimited list of spreads (e.g. mayonnaise, mustard)',
+    ),
+    'examples' => array(
+      'drush mmas turkey --spreads=ketchup,mustard' => 'Make a terrible-tasting sandwich that is lacking in pickles.',
+    ),
+    'aliases' => array('mmas'),
+    'bootstrap' => DRUSH_BOOTSTRAP_DRUSH, // No bootstrap at all.
+  );
+  
+  // Commandfiles may also add topics.  These will appear in
+  // the list of topics when `drush topic` is executed.
+  // To view this topic, run `drush --include=/full/path/to/examples topic`
+  $items['sandwich-exposition'] = array(
+    'description' => 'Ruminations on the true meaning and philosophy of sandwiches.',
+    'hidden' => TRUE,
+    'topic' => TRUE,
+    'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
+    'callback' => 'drush_print_file',
+    'callback arguments' => array(dirname(__FILE__) . '/sandwich-topic.txt'),
+  );
+
+  return $items;
+}
+
+/**
+ * Implementation of hook_drush_help().
+ *
+ * This function is called whenever a drush user calls
+ * 'drush help <name-of-your-command>'. This hook is optional. If a command
+ * does not implement this hook, the command's description is used instead.
+ *
+ * This hook is also used to look up help metadata, such as help
+ * category title and summary.  See the comments below for a description.
+ *
+ * @param
+ *   A string with the help section (prepend with 'drush:')
+ *
+ * @return
+ *   A string with the help text for your command.
+ */
+function sandwich_drush_help($section) {
+  switch ($section) {
+    case 'drush:make-me-a-sandwich':
+      return dt("This command will make you a delicious sandwich, just how you like it.");
+    // The 'title' meta item is used to name a group of
+    // commands in `drush help`.  If a title is not defined,
+    // the default is "All commands in ___", with the
+    // specific name of the commandfile (e.g. sandwich).
+    // Command files with less than four commands will 
+    // be placed in the "Other commands" section, _unless_
+    // they define a title.  It is therefore preferable
+    // to not define a title unless the file defines a lot
+    // of commands.
+    case 'meta:sandwich:title':
+      return dt("Sandwich commands");
+    // The 'summary' meta item is displayed in `drush help --filter`,
+    // and is used to give a general idea what the commands in this
+    // command file do, and what they have in common.
+    case 'meta:sandwich:summary':
+      return dt("Automates your sandwich-making business workflows.");
+  }
+}
+
+/**
+ * Implementation of drush_hook_COMMAND_validate().
+ *
+ * The validate command should exit with
+ * `return drush_set_error(...)` to stop execution of
+ * the command.  In practice, calling drush_set_error
+ * OR returning FALSE is sufficient.  See drush.api.php
+ * for more details.
+ */
+function drush_sandwich_make_me_a_sandwich_validate() {
+  $name = posix_getpwuid(posix_geteuid());
+  if ($name['name'] !== 'root') {
+    return drush_set_error('MAKE_IT_YOUSELF', dt('What? Make your own sandwich.'));
+  }
+}
+
+/**
+ * Example drush command callback. This is where the action takes place.
+ *
+ * The function name should be same as command name but with dashes turned to
+ * underscores and 'drush_commandfile_' prepended, where 'commandfile' is
+ * taken from the file 'commandfile.drush.inc', which in this case is 'sandwich'.
+ * Note also that a simplification step is also done in instances where
+ * the commandfile name is the same as the beginning of the command name,
+ * "drush_example_example_foo" is simplified to just "drush_example_foo".
+ * To also implement a hook that is called before your command, implement
+ * "drush_hook_pre_example_foo".  For a list of all available hooks for a
+ * given command, run drush in --debug mode.
+ *
+ * If for some reason you do not want your hook function to be named
+ * after your command, you may define a 'callback' item in your command
+ * object that specifies the exact name of the function that should be
+ * called.  However, the specified callback function must still begin
+ * with "drush_commandfile_" (e.g. 'callback' => "drush_example_foo_execute")
+ * if you want that all hook functions are still called (e.g.
+ * drush_example_pre_foo_execute, and so on).
+ *
+ * In this function, all of Drupal's API is (usually) available, including
+ * any functions you have added in your own modules/themes.
+ *
+ * @see drush_invoke()
+ * @see drush.api.php
+ */
+function drush_sandwich_make_me_a_sandwich($filling = 'ascii') {
+  $str_spreads = '';
+  if ($spreads = drush_get_option('spreads')) {
+    $list = implode(' and ', explode(',', $spreads));
+    $str_spreads = ' with just a dash of ' . $list;
+  }
+  $msg = dt('Okay. Enjoy this !filling sandwich!str_spreads.',
+            array('!filling' => $filling, '!str_spreads' => $str_spreads)
+         );
+  drush_print("\n" . $msg . "\n");
+  drush_print(file_get_contents(dirname(__FILE__) . '/sandwich.txt'));
+}

sites/all/modules/drush/examples/sandwich.txt

@@ -0,0 +1,24 @@
+ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+ . . .  . . . . . . . .:8 ;t;;t;;;;:..:;%SX888@X%t;.. . . . 
+ . .  .. . . . . . .%t%;%@%%%%%%%%%%X@8888XS%t;...:;ttt%X. .
+ . . .  . . . . . .X:8%X%%%XS%%%%%%%XS%%%%%@%%%%X%%%@%S88 . 
+ . . . . . .  .  . X@ @%%%X8X%%%88%%%8X%%%%%%%%%XXt@8@88@. .
+ . . . . .  . . .t@tS;%%8XSX%@XSX%@XSS%8@@88X@888X8SS S;S.  
+ . . . . . . .@%XS%%%%%S8@X%@8%XXSSXX%S@SSSX888.;@ 888@ . . 
+ . . . . . :.8:S%%%XS8X@@X%S@SSSS8SXSXXX%X88X:;@8@:S  88S. .
+ . . .  .8%S8%%%%%%8@SSSXXXSXSXSXSXSSS8S888 :@%:%XX:%8%:X:  
+ . .  .:8 %%%%@%%8@S%%XXSXSSSS8S@X%XSXX88 ;@X;SX88X8;%X88t. 
+ . . 88S%S%%%%8XSSXSX@@S@%XS8@SS%@S%888 88@S:8. .;.@%X:@8;. 
+ . .  88.8888888@XX   888888%X%@XX 88SS8@@;S@8.%;8@S%%:8   .
+ . .  S%:8 @SSSS8 @@8@8 8 88888888@%S:8:S8 @..%S SXX8888;. .
+ . . %:8S8888@88SXS S S::X@.8.8 X%S%8X:X88..% @@.S.%% .;. . 
+ .    .XX8@8;;%%t;;;;:@X@888888@888888.88S;8:8  ...    . . .
+ . . 8.;;@8@8:%%%%%t.8@%ttX@8@@@S8%8 X8S;X:@; :... . . . . .
+ . tS:8@;88.;:8888X8S:.tX88888X88  S8tStS88 :.. . . . . . . 
+ .:X;;:t%;tt%888S@8XS888@8.:tt@;88.tXXX8:::... . . . . . . .
+ .:X8St:8SXS XS8@X 8.8%888%X8@@X88tXS8t; . . . . . . .  . . 
+ .    :8888.88888888X@@X @ X X%S%;88;8t .. . .  . . . . .  .
+ ... ..: .    .@@888%St    @ @ 8SS 8:; . . . . . . . . . . .
+   .  .  .      ..::. ..:;;::::. ... . . . . . . . . . . . .
+ .. . . .     . .. . .  .  .  .. . . . . . .  . . . . . . . 

sites/all/modules/drush/examples/xkcd.drush.inc

@@ -0,0 +1,168 @@
+<?php
+
+/**
+ * @file
+ *   Example drush command.
+ *
+ *   To run this *fun* command, execute `drush --include=./examples xkcd`
+ *   from within your drush directory.
+ *
+ *   See `drush topic docs-commands` for more information about command authoring. 
+ *
+ *   You can copy this file to any of the following
+ *     1. A .drush folder in your HOME folder.
+ *     2. Anywhere in a folder tree below an active module on your site.
+ *     3. /usr/share/drush/commands (configurable)
+ *     4. In an arbitrary folder specified with the --include option.
+ */
+
+/**
+ * Implementation of hook_drush_command().
+ *
+ * In this hook, you specify which commands your
+ * drush module makes available, what it does and
+ * description.
+ *
+ * Notice how this structure closely resembles how
+ * you define menu hooks.
+ *
+ * See `drush topic docs-commands` for a list of recognized keys.
+ *
+ * @return
+ *   An associative array describing your command(s).
+ */
+function xkcd_drush_command() {
+  $items = array();
+
+  // The 'xkcd' command
+  $items['xkcd-fetch'] = array(
+    'description' => "Retrieve and display xkcd cartoons.",
+    'arguments' => array(
+      'search' => 'Optional argument to retrive the cartoons matching an index number, keyword search or "random". If omitted the latest cartoon will be retrieved.',
+    ),
+    'options' => array(
+      'image-viewer' => 'Command to use to view images (e.g. xv, firefox). Defaults to "display" (from ImageMagick).',
+      'google-custom-search-api-key' => 'Google Custom Search API Key, available from https://code.google.com/apis/console/. Default key limited to 100 queries/day globally.',
+    ),
+    'examples' => array(
+      'drush xkcd' => 'Retrieve and display the latest cartoon.',
+      'drush xkcd sandwich' => 'Retrieve and display cartoons about sandwiches.',
+      'drush xkcd 123 --image-viewer=eog' => 'Retrieve and display cartoon #123 in eog.',
+      'drush xkcd random --image-viewer=firefox' => 'Retrieve and display a random cartoon in Firefox.',
+    ),
+    'aliases' => array('xkcd'),
+    'bootstrap' => DRUSH_BOOTSTRAP_DRUSH, // No bootstrap at all.
+  );
+
+  return $items;
+}
+
+/**
+ * Implementation of hook_drush_help().
+ *
+ * This function is called whenever a drush user calls
+ * 'drush help <name-of-your-command>'. This hook is optional. If a command
+ * does not implement this hook, the command's description is used instead.
+ *
+ * This hook is also used to look up help metadata, such as help
+ * category title and summary.  See the comments below for a description.
+ *
+ * @param
+ *   A string with the help section (prepend with 'drush:')
+ *
+ * @return
+ *   A string with the help text for your command.
+ */
+function xkcd_drush_help($section) {
+  switch ($section) {
+    case 'drush:xkcd-fetch':
+      return dt("A command line tool (1) for a web site tool (2), that emulates
+(badly) a web based tool (3) that emulates (badly) a command line tool (4) to
+access a web site (5) with awesome geek humor.\n
+(1) Drush
+(2) Drupal
+(3) http://uni.xkcd.com/
+(4) BASH
+(5) http://xkcd.com/");
+  }
+}
+
+/**
+ * Example drush command callback. This is where the action takes place.
+ *
+ * The function name should be same as command name but with dashes turned to
+ * underscores and 'drush_commandfile_' prepended, where 'commandfile' is
+ * taken from the file 'commandfile.drush.inc', which in this case is 'sandwich'.
+ * Note also that a simplification step is also done in instances where
+ * the commandfile name is the same as the beginning of the command name,
+ * "drush_example_example_foo" is simplified to just "drush_example_foo".
+ * To also implement a hook that is called before your command, implement
+ * "drush_hook_pre_example_foo".  For a list of all available hooks for a
+ * given command, run drush in --debug mode.
+ *
+ * If for some reason you do not want your hook function to be named
+ * after your command, you may define a 'callback' item in your command
+ * object that specifies the exact name of the function that should be
+ * called.  However, the specified callback function must still begin
+ * with "drush_commandfile_" (e.g. 'callback' => "drush_example_foo_execute")
+ * if you want that all hook functions are still called (e.g.
+ * drush_example_pre_foo_execute, and so on).
+ *
+ * In this function, all of Drupal's API is (usually) available, including
+ * any functions you have added in your own modules/themes.
+ *
+ * @see drush_invoke()
+ * @see drush.api.php
+ *
+ * @param
+ *   An optional string with search keyworks, cartoon ID or "random".
+ */
+function drush_xkcd_fetch($search = '') {
+  if (empty($search)) {
+    drush_xkcd_display('http://xkcd.com');
+  }
+  elseif (is_numeric($search)) {
+    drush_xkcd_display('http://xkcd.com/' . $search);
+  }
+  elseif ($search == 'random') {
+    $xkcd_response = @json_decode(file_get_contents('http://xkcd.com/info.0.json'));
+    if (!empty($xkcd_response->num)) {
+      drush_xkcd_display('http://xkcd.com/' . rand(1, $xkcd_response->num));
+    }
+  }
+  else {
+    // This uses an API key with a limited number of searches per 
+    $search_response = @json_decode(file_get_contents('https://www.googleapis.com/customsearch/v1?key=' . drush_get_option('google-custom-search-api-key', 'AIzaSyDpE01VDNNT73s6CEeJRdSg5jukoG244ek') . '&cx=012652707207066138651:zudjtuwe28q&q=' . $search));
+    if (!empty($search_response->items)) {
+      foreach ($search_response->items as $item) {
+        drush_xkcd_display($item->link);
+      }
+    }
+    else {
+      drush_set_error('DRUSH_XKCD_SEARCH_FAIL', dt('The search failed or produced no results.'));
+    }
+  }
+}
+
+/**
+ * Retrieve and display a table of metadata for an XKCD cartoon,
+ * then retrieve and display the cartoon using a specified image viewer.
+ *
+ * @param
+ *   A string with the URL of the cartoon to display.
+ */
+function drush_xkcd_display($url) {
+  $xkcd_response = @json_decode(file_get_contents($url . '/info.0.json'));
+  if (!empty($xkcd_response->num)) {
+    $data = (array)$xkcd_response;
+    $data['date'] = $data['year'] . '/' . $data['month'] . '/' . $data['day'];
+    unset($data['safe_title'], $data['news'], $data['link'], $data['year'], $data['month'], $data['day']);
+    drush_print_table(drush_key_value_to_array_table($data));
+    $img = realpath(_drush_download_file($data['img']));
+    drush_register_file_for_deletion($img);
+    drush_shell_exec(drush_get_option('image-viewer', 'display') . ' ' . $img);
+  }
+  else {
+    drush_set_error('DRUSH_XKCD_METADATA_FAIL', dt('Unable to retrieve cartoon metadata.'));
+  }
+}