bachir/popsu-d7
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

first import

Browse Source
This commit is contained in:
Bachir Soussi Chiadmi
2015-04-08 11:40:19 +02:00
commit 1bc61b12ad
8435 changed files with 1582817 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
sites/all/modules/drush/docs/bootstrap.html Normal file
View File

@@ -0,0 +1,135 @@
<h1>The Drush Bootstrap Process</h1>
<p>
When preparing to run a command, 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.
<p>
For efficiency and convenience, some drush commands can work
without first bootstrapping a Drupal site, or by only partially
bootstrapping a site. This is more efficient, because there is
sometimes a slight delay involved with bootstrapping, especially
in some of the later stages. It is also a matter of convenience,
because some commands are useful to use even when you do not
have a working Drupal site available to bootstrap. For example,
you can use drush to download Drupal with `drush dl drupal`. This
obviously does not require any bootstrapping to work.
<p>
The drush bootstrapping process is also very closely related with
drush configuration files. At each bootstrap phase, drush may load
additional configuration files that may contain additional drush
settings. This has two very important connotations. First, settings
that are only loaded in a later bootstrap phase are not available
for commands that do not reach that bootstrap phase. Second, it
is possible to alter drush behavior on a per-site basis by applying
settings in a site-specific configuration file. See
`drush topic docs-configuration` for details on drush configuration
files.
<h2>DRUSH_BOOTSTRAP_DRUSH</h2>
<p>
Configuration files loaded during this phase:<ul>
<li>Drush installation folder.
<li>System wide configuration folder (e.g. /etc/drush/drushrc.php).
<li>User's .drush folder (i.e. ~/.drush/drushrc.php).
<li>In any location, as specified by the --config (-c) option.
</ul><p>
Only bootstrap Drush, without any Drupal specific code.
<p>
Any code that operates on the Drush installation, and not specifically
any Drupal directory, should bootstrap to this phase.
<h2>DRUSH_BOOTSTRAP_DRUPAL_ROOT</h2>
<p>
Configuration files loaded during this phase:<ul>
<li>Drupal installation root.
</ul><p>
Set up and test for a valid drupal root, either through the -r/--root options,
or evaluated based on the current working directory.
<p>
Any code that interacts with an entire Drupal installation, and not a specific
site on the Drupal installation should use this bootstrap phase.
<h2>DRUSH_BOOTSTRAP_DRUPAL_SITE</h2>
<p>
Configuration files loaded during this phase:<ul>
<li>Drupal site folder (e.g sites/{default|example.com}/drushrc.php).
</ul><p>
Set up a Drupal site directory and the correct environment variables to
allow Drupal to find the configuration file.
<p>
If no site is specified with the -l / --uri options, Drush will assume the
site is 'default', which mimics Drupal's behaviour.
<p>
If you want to avoid this behaviour, it is recommended that you use the
DRUSH_BOOTSTRAP_DRUPAL_ROOT bootstrap phase instead.
<p>
Any code that needs to modify or interact with a specific Drupal site's
settings.php file should bootstrap to this phase.
<h2>DRUSH_BOOTSTRAP_DRUPAL_CONFIGURATION</h2>
<p>
Load the settings from the Drupal sites directory.
<p>
This phase is analagous to the DRUPAL_BOOTSTRAP_CONFIGURATION bootstrap phase in Drupal
itself, and this is also the first step where Drupal specific code is included.
<p>
This phase is commonly used for code that interacts with the Drupal install API,
as both install.php and update.php start at this phase.
<h2>DRUSH_BOOTSTRAP_DRUPAL_DATABASE</h2>
<p>
Connect to the Drupal database using the database credentials loaded
during the previous bootstrap phase.
<p>
This phase is analogous to the DRUPAL_BOOTSTRAP_DATABASE bootstrap phase in
Drupal.
<p>
Any code that needs to interact with the Drupal database API needs to
be bootstrapped to at least this phase.
<h2>DRUSH_BOOTSTRAP_DRUPAL_FULL</h2>
<p>
Fully initialize Drupal.
<p>
This is the default bootstrap phase all commands will try to reach,
unless otherwise specified.
This is analogous to the DRUPAL_BOOTSTRAP_FULL bootstrap phase in
Drupal.
<p>
Any code that interacts with the general Drupal API should be
bootstrapped to this phase.
<h2>DRUSH_BOOTSTRAP_DRUPAL_LOGIN</h2>
<p>
Log in to the initialiased Drupal site.
<p>
This bootstrap phase is used after the site has been
fully bootstrapped.
<p>
This phase will log you in to the drupal site with the username
or user ID specified by the --user/ -u option.
<p>
Use this bootstrap phase for your command if you need to have access
to information for a specific user, such as listing nodes that might
be different based on who is logged in.
<h2>DRUSH_BOOTSTRAP_MAX</h2>
<p>
This is not an actual bootstrap phase. Commands that use
DRUSH_BOOTSTRAP_MAX will cause drush to bootstrap as far
as possible, and then run the command regardless of the
bootstrap phase that was reached. This is useful for drush
commands that work without a bootstrapped site, but that
provide additional information or capabilities in the presence
of a bootstrapped site. For example, `drush pm-releases modulename`
works without a bootstrapped Drupal site, but will include
the version number for the installed module if a Drupal site
has been bootstrapped.

254
sites/all/modules/drush/docs/commands.html Normal file
View File

@@ -0,0 +1,254 @@
<h1>Creating Custom Drush Commands</h1>
<p>
Creating a new drush command is very easy. There are
four simple steps.
<ol>
<li>Create a command file called COMMANDFILE.drush.inc
<li>Implement the function COMMANDFILE_drush_help(). Optional.
<li>Implement the function COMMANDFILE_drush_command()
<li>Implement the functions that your commands will call.
These will usually be named drush_COMMANDFILE_COMMANDNAME().
</ol><p>
For an example drush command, see examples/sandwich.drush.inc.
The steps for implementing your command are explained in more
detail below.
<h2>Create COMMANDFILE.drush.inc</h2>
<p>
The name of your drush command is very important. It must end
in ".drush.inc" to be recognized as a drush command. The part
of the filename that comes before the ".drush.inc" becomes the
name of the commandfile. Your commandfile name is used by
drush to compose the names of the functions it will call, so
choose wisely.
<p>
The example drush command, 'make-me-a-sandwich', is stored
in the 'sandwich' commandfile, 'sandwich.drush.inc'.
<p>
Drush searches for commandfiles in the following locations:
<ul>
<li>The "/path/to/drush/commands" folder.
<li>Folders listed in the 'include' option (see `drush topic docs-configuration`).
<li>The system-wide drush commands folder, e.g. /usr/share/drush/commands
<li>The ".drush" folder in the user's HOME folder.
<li>All modules in the current Drupal installation
</ul> <p>
Note that modules in the current Drupal installation will only
be considered if drush has bootstrapped to at least the DRUSH_BOOSTRAP_SITE
level. Usually, when working with a Drupal site, drush will
bootstrap to DRUSH_BOOTSTRAP_FULL; in this case, only the drush
commandfiles in enabled modules will be considered eligible for
loading. If a drush only bootstraps to DRUSH_BOOTSTRAP_SITE,
though, then all drush commandfiles will be considered, whether the
module is enabled or not. See `drush topic docs-bootstrap` for
more information on bootstrapping.
<p>
Additionally, drush commandfiles may optionally define a function
COMMANDFILE_drush_load() in the file COMMANDFILE.drush.load.inc.
If this function returns FALSE, then the commandfile will not be loaded.
<h2>Implement COMMANDFILE_drush_help()</h2>
<p>
The drush_help hook is an optional place to describe a command in long form. If
the command only requires a brief description, use the description key in
COMMANDFILE_drush_command(). The drush_help hook for the 'sandwich' commandfile looks
like this:
<pre>
function sandwich_drush_help($section) {
switch ($section) {
case 'drush:make-me-a-sandwich':
return dt("... brief help summary goes here ...");
}
}
</pre><p>
Note that the command name is prepended with 'drush:' in
the drush_help hook. Your commandfile may implement
multiple commands; to do so, just add more 'case' statements
to the switch, one for each command.
<h2>Implement COMMANDFILE_drush_command()</h2>
<p>
The drush_command hook is the most important part of the
commandfile. It returns an array of items that define
how your commands should be called, and how they work.
Drush commands are very similar to the Drupal menu system.
The elements that can appear in a drush command definition
are shown below.
<ul>
<li>'aliases':
Provides a list of shorter names for the command.
For example, pm-download may also be called via `drush dl`.
If the alias is used, drush will substitute back in the
primary command name, so pm-download will still be used
to generate the command hook, etc.
<li>'deprecated-aliases':
Works just like 'aliases', but does not
appear in help. Used in instances where the drush
maintainers intend to eventually remove support for a
command alias. If someone runs a drush command using a
deprecated alias, drush will print a warning message.
<li>'command hook':
Change the name of the function drush will
call to execute the command from drush_COMMANDFILE_COMMANDNAME()
to drush_COMMANDFILE_COMMANDHOOK(), where COMMANDNAME is the
original name of the command, and COMMANDHOOK is the value
of the 'command hook' item.
<li>'callback':
Name of function to invoke for this command. The callback
function name _must_ begin with "drush_commandfile_", where commandfile
is from the file "commandfile.drush.inc", which contains the
commandfile_drush_command() function that returned this command.
Note that the callback entry is optional; it is preferable to
omit it, in which case drush_invoke() will generate the hook function name.
<li>'callback arguments':
An array of arguments to pass to the callback.
The command line arguments, if any, will appear after the
callback arguments in the function parameters.
<li>'description':
Description of the command.
<li>'arguments':
An array of arguments that are understood by the command.
Used by `drush help` only.
<li>'options':
An array of options that are understood by the command.
Used by `drush help` only.
<li>'examples':
An array of examples that are understood by the command.
Used by `drush help` only.
<li>'scope':
One of 'system', 'project', 'site'. Not currently used.
<li>'bootstrap':
Drupal bootstrap level. Valid values are:
<ul>
<li>DRUSH_BOOTSTRAP_DRUSH
<li>DRUSH_BOOTSTRAP_DRUPAL_ROOT
<li>DRUSH_BOOTSTRAP_DRUPAL_SITE
<li>DRUSH_BOOTSTRAP_DRUPAL_CONFIGURATION
<li>DRUSH_BOOTSTRAP_DRUPAL_DATABASE
<li>DRUSH_BOOTSTRAP_DRUPAL_FULL
<li>DRUSH_BOOTSTRAP_DRUPAL_LOGIN
<li>DRUSH_BOOTSTRAP_MAX
</ul>
See `drush topic docs-bootstrap`.
<li>'core':
Drupal major version required. Append a '+' to indicate 'and later versions.'
<li>'drupal dependencies':
Drupal modules required for this command.
<li>'drush dependencies':
Other drush commandfiles required for this command.
<li>'topics':
Provides a list of topic commands that are related in
some way to this command. Used by `drush help` only.
<li>'topic':
Set to TRUE if this command is a topic, callable from the
`drush docs-topics` command.
</ul><p>
The 'sandwich' drush_command hook looks like this:
<pre>
function sandwich_drush_command() {
$items = array();
$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.
);
return $items;
}
</pre><p>
Most of the items in the 'make-me-a-sandwich' command
definition have no effect on execution, and are used only
by `drush help`. The exceptions are 'aliases' (described
above) and 'bootstrap'. As previously mentioned,
`drush topic docs-bootstrap` explains the drush bootstrapping
process in detail.
<h2>Implement drush_COMMANDFILE_COMMANDNAME()</h2>
<p>
The 'make-me-a-sandwich' command in sandwich.drush.inc
is defined as follows:
<pre>
function drush_sandwich_make_me_a_sandwich($filling = 'ascii') {
... implementation here ...
}
</pre><p>
If a user runs `drush make-me-a-sandwich` with no command line
arguments, then drush will call drush_sandwich_make_me_a_sandwich()
with no function parameters; in this case, $filling will take on
the provided default value, 'ascii'. (If there is no default
value provided, then the variable will be NULL, and a warning
will be printed.) Running `drush make-me-a-sandwich ham` will
cause drush to call drush_sandwich_make_me_a_sandwich('ham'). In
the same way, commands that take two command line arguments can
simply define two functional parameters, and a command that takes
a variable number of command line arguments can use the standard
php function func_get_args() to get them all in an array for easy
processing.
<p>
Note that drush will actually call a sequence of functions before
and after your drush command function. One of these hooks is the
"validate" hook. The 'sandwich' commandfile provides a validate
hook for the 'make-me-a-sandwich' command:
<pre>
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.'));
}
}
</pre><p>
The validate function should call drush_set_error and return
its result if the command cannot be validated for some reason.
See `drush topic docs-policy` for more information on defining
policy functions with validate hooks, and `drush topic docs-api`
for information on how the command hook process works. Also,
the list of defined drush error codes can be found in
`drush topic docs-errorcodes`.

73
sites/all/modules/drush/docs/context.html Normal file
View File

@@ -0,0 +1,73 @@
<h1>Drush Contexts</h1>
<p>
The drush contexts API acts as a storage mechanism for all options,
arguments and configuration settings that are loaded into drush.
<p>
This API also acts as an IPC mechanism between the different drush commands,
and provides protection from accidentally overriding settings that are
needed by other parts of the system.
<p>
It also avoids the necessity to pass references through the command chain
and allows the scripts to keep track of whether any settings have changed
since the previous execution.
<p>
This API defines several contexts that are used by default.
<h2>Argument contexts</h2>
<p>
These contexts are used by Drush to store information on the command.
They have their own access functions in the forms of
drush_set_arguments(), drush_get_arguments(), drush_set_command(),
drush_get_command().
<ul>
<li>command : The drush command being executed.</li>
<li>arguments : Any additional arguments that were specified.</li>
</ul>
<h2>Setting contexts</h2>
<p>
These contexts store options that have been passed to the drush.php
script, either through the use of any of the config files, directly from
the command line through --option='value' or through a JSON encoded string
passed through the STDIN pipe.
<p>
These contexts are accessible through the drush_get_option() and
drush_set_option() functions. See drush_context_names() for a description
of all of the contexts.
<p>
Drush commands may also choose to save settings for a specific context to
the matching configuration file through the drush_save_config() function.
<h2>Available Setting contexts</h2>
<p>
These contexts are evaluated in a certain order, and the highest priority value
is returned by default from drush_get_option. This allows scripts to check whether
an option was different before the current execution.
<p>
Specified by the script itself :
<ul>
<li>process : Generated in the current process.
<li>cli : Passed as --option=value to the command line.
<li>stdin : Passed as a JSON encoded string through stdin.
<li>alias : Defined in an alias record, and set in the
alias context whenever that alias is used.
<li>specific : Defined in a command-specific option record, and
set in the command context whenever that command is used.
</ul>
<p>
Specified by config files :
<ul>
<li>custom : Loaded from the config file specified by --config or -c
<li>site : Loaded from the drushrc.php file in the Drupal site directory.
<li>drupal : Loaded from the drushrc.php file in the Drupal root directory.
<li>user : Loaded from the drushrc.php file in the user's home directory.
<li>drush : Loaded from the drushrc.php file in the $HOME/.drush directory.
<li>system : Loaded from the drushrc.php file in the system's $PREFIX/etc/drush directory.
<li>drush : Loaded from the drushrc.php file in the same directory as drush.php.
</ul>
<p>
Specified by the script, but has the lowest priority :
<ul>
<li>default : The script might provide some sensible defaults during init.
</ul>

270
sites/all/modules/drush/docs/drush.api.php Normal file
View File

@@ -0,0 +1,270 @@
<?php
/**
* @file
* Documentation of the Drush API.
*
* All drush commands are invoked in a specific order, using
* drush-made hooks, very similar to the Drupal hook system. See drush_invoke()
* for the actual implementation.
*
* For any commandfile named "hook", the following hooks are called, in
* order, for the command "COMMAND":
*
* 0. drush_COMMAND_init()
* 1. drush_hook_COMMAND_validate()
* 2. drush_hook_pre_COMMAND()
* 3. drush_hook_COMMAND()
* 4. drush_hook_post_COMMAND()
*
* For example, here are the hook opportunities for a mysite.drush.inc file
* that wants to hook into the `pm-download` command.
*
* 1. drush_mysite_pm_download_validate()
* 2. drush_mysite_pre_pm_download()
* 3. drush_mysite_pm_download()
* 4. drush_mysite_post_pm_download()
*
* Note that the drush_COMMAND_init() hook is only for use by the
* commandfile that defines the command.
*
* If any of hook function fails, either by calling drush_set_error
* or by returning FALSE as its function result, then the rollback
* mechanism is called. To fail with an error, call drush_set_error:
*
* return drush_set_error('MY_ERROR_CODE', dt('Error message.'));
*
* To allow the user to confirm or cancel a command, use drush_confirm
* and drush_user_abort:
*
* if (!drush_confirm(dt('Are you sure?'))) {
* return drush_user_abort();
* }
*
* The rollback mechanism will call, in reverse, all _rollback hooks.
* The mysite command file can implement the following rollback hooks:
*
* 1. drush_mysite_post_pm_download_rollback()
* 2. drush_mysite_pm_download_rollback()
* 3. drush_mysite_pre_pm_download_rollback()
* 4. drush_mysite_pm_download_validate_rollback()
*
* Before any command is called, hook_drush_init() is also called.
* hook_drush_exit() is called at the very end of command invocation.
*
* @see includes/command.inc
*
* @see hook_drush_init()
* @see drush_COMMAND_init()
* @see drush_hook_COMMAND_validate()
* @see drush_hook_pre_COMMAND()
* @see drush_hook_COMMAND()
* @see drush_hook_post_COMMAND()
* @see drush_hook_post_COMMAND_rollback()
* @see drush_hook_COMMAND_rollback()
* @see drush_hook_pre_COMMAND_rollback()
* @see drush_hook_COMMAND_validate_rollback()
* @see hook_drush_exit()
*/
/**
* @addtogroup hooks
* @{
*/
/**
* Take action before any command is run. Logging an error stops command execution.
*/
function hook_drush_init() {
}
/**
* Initialize a command prior to validation. If a command
* needs to bootstrap to a higher level, this is best done in
* the command init hook. It is permisible to bootstrap in
* any hook, but note that if bootstrapping adds more commandfiles
* (*.drush.inc) to the commandfile list, the newly-added
* commandfiles will not have any hooks called until the next
* phase. For example, a command that calls drush_bootstrap_max()
* in drush_hook_COMMAND() would only permit commandfiles from
* modules enabled in the site to participate in drush_hook_post_COMMAND()
* hooks.
*/
function drush_COMMAND_init() {
drush_bootstrap_max();
}
/**
* Run before a specific command executes.
*
* Logging an error stops command execution, and the rollback function (if any)
* for each hook implementation is invoked.
*
* @see drush_hook_COMMAND_validate_rollback()
*/
function drush_hook_COMMAND_validate() {
}
/**
* Run before a specific command executes. Logging an error stops command execution.
*
* Logging an error stops command execution, and the rollback function (if any)
* for each hook implementation is invoked, in addition to the
* validate rollback.
*
* @see drush_hook_pre_COMMAND_rollback()
* @see drush_hook_COMMAND_validate_rollback()
*/
function drush_hook_pre_COMMAND() {
}
/**
* Implementation of the actual drush command.
*
* This is where most of the stuff should happen.
*
* Logging an error stops command execution, and the rollback function (if any)
* for each hook implementation is invoked, in addition to pre and
* validate rollbacks.
*
* @see drush_hook_COMMAND_rollback()
* @see drush_hook_pre_COMMAND_rollback()
* @see drush_hook_COMMAND_validate_rollback()
*/
function drush_hook_COMMAND() {
}
/**
* Run after a specific command executes. Logging an error stops command execution.
*
* Logging an error stops command execution, and the rollback function (if any)
* for each hook implementation is invoked, in addition to pre, normal
* and validate rollbacks.
*
* @see drush_hook_post_COMMAND_rollback()
* @see drush_hook_COMMAND_rollback()
* @see drush_hook_pre_COMMAND_rollback()
* @see drush_hook_COMMAND_validate_rollback()
*/
function drush_hook_post_COMMAND() {
}
/**
* Take action after any command is run.
*/
function hook_drush_exit() {
}
/*
* A commandfile may choose to decline to load for the current bootstrap
* level by returning FALSE. This hook must be placed in MODULE.drush.load.inc.
* @see drush_commandfile_list().
*/
function hook_drush_load() {
}
/**
* Take action after a project has been downloaded.
*/
function hook_drush_pm_post_download($project, $release) {
}
/**
* Take action after a project has been updated.
*/
function hook_pm_post_update($release_name, $release_candidate_version, $project_parent_path) {
}
/**
* Adjust the location that a project should be copied to after being downloaded.
*
* See @pm_drush_pm_download_destination_alter().
*/
function hook_drush_pm_download_destination_alter(&$project, $release) {
if ($some_condition) {
$project['project_install_location'] = '/path/to/install/to/' . $project['project_dir'];
}
}
/**
* Add information to the upgrade project map; this information
* will be shown to the user when upgrading Drupal to the next
* major version if the module containing this hook is enabled.
*
* @see drush_upgrade_project_map().
*/
function hook_drush_upgrade_project_map_alter(&$project_map) {
$project_map['warning']['hook'] = dt("You need to take special action before upgrading this module. See http://mysite.com/mypage for more information.");
}
/**
* Sql-sync sanitization example. This is equivalent to
* the built-in --sanitize option of sql-sync, but simplified
* to only work with default values on Drupal 6 + mysql.
*
* @see sql_drush_sql_sync_sanitize().
*/
function hook_drush_sql_sync_sanitize($source) {
drush_sql_register_post_sync_op('my-sanitize-id',
dt('Reset passwords and email addresses in user table'),
"update users set pass = MD5('password'), mail = concat('user+', uid, '@localhost') where uid > 0;");
}
/**
* Take action before modules are disabled in a major upgrade.
* Note that when this hook fires, it will be operating on a
* copy of the database.
*/
function drush_hook_pre_site_upgrade_prepare() {
// site upgrade prepare will disable contrib_extensions and
// uninstall the uninstall_extension
$contrib_extensions = func_get_args();
$uninstall_extensions = explode(',', drush_get_option('uninstall', ''));
}
/**
* Add help components to a command
*/
function hook_drush_help_alter(&$command) {
if ($command['command'] == 'sql-sync') {
$command['options']['myoption'] = "Description of modification of sql-sync done by hook";
$command['sub-options']['sanitize']['my-sanitize-option'] = "Description of sanitization option added by hook (grouped with --sanitize option)";
}
}
/**
* Add/edit options to cache-clear command
*/
function hook_drush_cache_clear(&$types) {
$types['views'] = 'views_invalidate_cache';
}
/*
* Make shell aliases and other .bashrc code available during core-cli command.
*
* @return
* Bash code typically found in a .bashrc file.
*
* @see core_cli_bashrc() for an example implementation.
*/
function hook_cli_bashrc() {
$string = "
alias siwef='drush site-install wef --account-name=super --account-mail=me@wef'
alias dump='drush sql-dump --structure-tables-key=wef --ordered-dump'
";
return $string;
}
/**
* @} End of "addtogroup hooks".
*/

80
sites/all/modules/drush/docs/shellscripts.html Normal file
View File

@@ -0,0 +1,80 @@
<h1>The Drush Shell Scripts</h1>
<p>
A drush shell script is any Unix shell script file that has
its "execute" bit set (i.e., via `chmod +x myscript.drush`)
and that begins with a specific line:
<pre>
#!/usr/bin/env drush
</pre>
- or -
<pre>
#!/full/path/to/drush
</pre><p>
The former is the usual form, and is more convenient in that
it will allow you to run the script regardless of where drush
has been installed on your system, as long as it appears in
your PATH. The later form allows you to specify the drush
command add options to use, as in:
<pre>
#!/full/path/to/drush php-script --some-option
</pre><p>
Adding specific options is important only in certain cases,
described later; it is usually not necessary.
<p>
Drush scripts do not need to be named "*.drush" or "*.script";
they can be named anything at all. To run them, make sure they
are executable (`chmod +x helloworld.script`) and then run them
from the shell like any other script.
<p>
There are two big advantages to drush scripts over bash scripts:
<ul>
<li>They are written in php
<li>drush can bootstrap your Drupal site before
running your script.
</ul><p>
To bootstrap a Drupal site, provide an alias to the site to
bootstrap as the first commandline argument.
<p>
For example:
<pre>
$ helloworld.script @dev a b c
</pre><p>
If the first argument is a valid site alias, drush will remove
it from the arument list and bootstrap that site, then run
your script. The script itself will not see @dev on its
argument list. If you do not want drush to remove the first
site alias from your scripts argument list (e.g. if your script
wishes to syncronise two sites, specified by the first two
arguments, and does not want to bootstrap either of those
two sites), then fully specify the drush command (php-script)
and options to use, as shown above. By default, if the drush
command is not specified, drush will provide the following default
line:
<pre>
#!/full/path/to/drush php-script --bootstrap-to-first-arg
</pre><p>
It is the option --bootstrap-to-first-arg that causes drush to
pull off the first argument and bootstrap it. The way to get rid
of that option is to specify the php-script line to run, and leave
it off, like so:
<pre>
#!/full/path/to/drush php-script
</pre><p>
Note that 'php-script' is the only built-in drush command that
makes sense to put on the "shebang" ("#!" is pronounced "shebang")
line. However, if you wanted to, you could implement your own
custom version of php-script (e.g. to preprocess the script input,
perhaps), and specify that command on the shebang line.
<p>
Drush scripts can access their arguments via the drush_shift()
function:
<pre>
while ($arg = drush_shift()) {
drush_print($arg);
}
</pre><p>
Options are available via drush_get_option('option-name').
<p>
See the example drush script in `drush topic docs-examplescript`,
and the list of drush error codes in `drush topic docs-errorcodes`.

100
sites/all/modules/drush/docs/upgrade.html Normal file
View File

@@ -0,0 +1,100 @@
<h1>Using Drush to Upgrade Drupal 6.x to Drupal 7.x</h1>
<p>
The drush site-upgrade command supports upgrades from Drupal 6.x
to Drupal 7.x. Upgrades from Drupal 7.x to Drupal 8.x will be
supported in the future. Use the drush pm-update command to do minor verison
updates for Drupal 5.x, 6.x and 7.x.
<p>
To begin, consult the UPGRADE.txt file from the root folder of the
version of Drupal you are upgrading to. Drush will handle some of
the steps described there, but not all. In particular, you should
make sure that your current Drupal installation is running on the
most recent minor version available.
<p>
n.b. At the time of this writing, Drupal 6.20 and Drupal 7.0 were
the most recent versions available. Always check primary sources
prior to upgrading to see if anything may have changed.
<h2>Upgrade a Copy of your Site</h2>
<p>
Drush will always upgrade <i>from</i> the specified Drupal site
<i>to</i> an empty Drupal site. It is necessary to create a
site alias to describe the destination site. Site aliases are
described in `drush topic docs-aliases`. A canonical site alias
is adequate to define your target site for upgrade:
<p>
$aliases['onward'] = { <br>
'root' => '/path/to/upgraded/drupalroot',<br>
'uri' => 'http://onward.mysite.org',<br>
}<br>
<p>
Optionally, you might also want to define 'db_url' to specify
the name of your target database. If you do not, drush will
compose a database name for you based on the name of your site alias.
<p>
<h2>Running the `site-upgrade` Command</h2>
<p>
Drush will upgrade the current bootstrapped site, and will
put the result in the target site specified by the argument
to the command. For example:
<p>
drush @from site-upgrade @onward
<p>
The site-upgrade command will perform the following operations:
<ol>
<li>Download the next major release of Drupal and store the files
in the target site.</li>
<li>Write a new settings.php file with an appropriate databases
structure for the new target site.</li>
<li>Make a copy of the SQL database for the new site.</li>
<li>The default theme for the new site will be set to "garland",
and the admin theme will be set to "seven".</li>
<li>All non-core extensions will be disabled in the target database,
and updatedb will be run on Drupal core.</li>
<li>All of the modules disabled in the previous step will be
downloaded again, if they have an appropriate version for the
target Drupal site available.</li>
<li>updatedb will be run again to update the non-core modules.</li>
<li>All of the non-core modules will be enabled again.</li>
</ol>
<p>
Before drush begins this process, it will first print out a list
of warnings for any modules that may not be ready to upgrade yet.
Please read all of these messages carefully before proceding.
Here are some of the situations you may encounter.
<ul>
<li>If a module has no <i>recommended</i> release, then drush
will continue, downloading an available release for the upgrade.</li>
<li>If a module has no release at all, then drush will skip it.
The module's data will remain in the database.</li>
<li>You may discover that some modules, such as date_api, might
cause the Drupal core updatedb to fail. In this instance, you
may use the --uninstall option to list the modules to uninstall
prior to upgrade. Modules uninstalled in this manner will have
all of their data removed from the target database; the database
of the source site is not affected.</li>
</ul>
<p>
When drush is enabling the modules in the upgraded site, if there
are any new dependencies, they will also be identified and downloaded
if possible. For example, views-7.x depends on the ctools module
from the Chaos tool suite, whereas views-6 did not; drush will therefore
download and enable ctools when upgrading the views module from
Drupal 6 to Drupal 7.
<p>
There will still be some work left to do after the site-upgrade
command has completed; for example, you will still need to port your
theme and any custom modules to the new version of Drupal, and some
contrib modules may require additional work to update their configuration
settings. Using site-upgrade will all the same save you a considerable
amount of time. There is no risk in trying it; if it does not work,
you can always start over, or run it at a later date when more contrib
modules have been updated. If you do run site-upgrade a second time
on the same site, drush will ask you if you want to replace the existing
target site, effectively starting over from the beginning, or re-use
the site that is already present. In the later case, drush will use
the existing code, but will re-copy the source database and run updatedb
on it again. This will all you to attempt to fix any non-working contrib
modules yourself to get your site-upgrade working.
<p>
Enjoy!