README.txt

  1. 6.x tests/README.txt
  2. 3.x README.txt
  3. 4.x tests/README.txt
  4. 4.x README.txt
  5. 5.x tests/README.txt
  6. 5.x README.txt
  7. 5.x lib/README.txt
DESCRIPTION
-----------
Drush is a command line shell and Unix scripting interface for Drupal.
If you are unfamiliar with shell scripting, reviewing the documentation
for your shell (e.g. man bash) or reading an online tutorial (e.g. search
for "bash tutorial") will help you get the most out of Drush.

Drush core ships with lots of useful commands for interacting with code
like modules/themes/profiles. Similarly, it runs update.php, executes sql
queries and DB migrations, and misc utilities like run cron or clear cache.

REQUIREMENTS
------------
* To use drush from the command line, you'll need a CLI-mode capable PHP
  binary. The minimum PHP version is 5.2.
* Drush 4 does not support Windows; see "For Windows", below.
* Drush works with Drupal 5, Drupal 6 and Drupal 7.  However, occasionally
  recent changes to the most recent version of Drupal can introduce issues
  with drush.  On Drupal 5, drush requires update_status v5.x-2.5 or later
  in order to use pm-updatecode.  If you have an earlier version of update_status,
  upgrade it via "drush dl update_status" before using pm-updatecode.


INSTALLATION
------------
For Linux/Unix/Mac:
  1. Untar the tarball into a folder outside of your web site (/path/to/drush)
     (e.g. if drush is in your home directory, ~/drush can be used for /path/to/drush)
  2. Make the 'drush' command executable:
       $ chmod u+x /path/to/drush/drush
  3. (Optional, but recommended:) To ease the use of drush,
     - create a link to drush in a directory that is in your PATH, e.g.:
       $ ln -s /path/to/drush/drush /usr/local/bin/drush
     OR
     - add the folder that contains drush to your PATH
       PATH=$PATH:/path/to/drush

       This goes into .profile, .bash_aliases or .bashrc in your home folder.
       NOTE:  You must log out and then log back in again or re-load your bash
       configuration file to apply your changes to your current session:
       $ source .bashrc

     NOTE FOR ADVANCED USERS
     - If you want to run drush with a specific version of php, rather than the
       one found by the drush command, you can define an environment variable
       DRUSH_PHP that points to the php to execute:
       export DRUSH_PHP=/usr/bin/php5
     OR
     - If you want to exactly control how drush is called, you may define an alias
       that executes the drush.php file directly and passes that path to drush:
       $ alias drush='/path/to/php/php5 -d memory_limit=128M /path/to/drush/drush.php --php="/path/to/php/php5 -d memory_limit=128M"'
       Note that it is necessary to pass the '--php' option to drush to define
       how drush should call php if it needs to do so.
       If you define an alias, to allow Drush to detect the number of available columns,
       you need to add the line 'export COLUMNS' to the .profile file in your
       home folder.

     NOTE ON PHP.INI FILES
     - Usually, php is configured to use separate php.ini files for the web server
       and the command line.  To see which php.ini file drush is using, run:
       $ drush status
     - Compare the php.ini that drush is using with the php.ini that the webserver is
       using.  Make sure that drush's php.ini is given as much memory to work with as
       the web server is; otherwise, Drupal might run out of memory when drush
       bootstraps it.
     - Drush requires a fairly unrestricted php environment to run in.  In particular,
       you should insure that safe_mode, open_basedir, disable_functions and
       disable_classes are empty.
     - If drush is using the same php.ini file as the web server, you can create
       a php.ini file exclusively for drush by copying your web server's php.ini
       file to the folder $HOME/.drush or the folder /etc/drush.  Then you may edit
       this file and change the settings described above without affecting the
       php enviornment of your web server.  Alternately, if you only want to
       override a few values, copy example.drush.ini from the "examples" folder
       into $HOME/.drush or the folder /etc/drush and edit to suit.  See comments
       in example.drush.ini for more details.
       
  4. Start using drush by running "drush" from your Drupal root directory.

     (or, if you did not follow step 3, by running "/path/to/drush/drush"
      or navigating to /path/to/drush and running "./drush" )

    If you have troubles, try using the -l and -r options when invoking drush. See below.

For Windows:
  - Drush 4 does not support Windows.  Consider using Drush 3 or Drush 5 instead.
  - Consider using on Linux/Unix/OSX using Virtualbox or other VM. Windows support is lacking.
  - The Drush 5 Windows installer can be found at http://drush.ws/drush_windows_installer.
  - Instructions for installing Drush 3 on Windows can be found at 
    http://drupal.org/node/594744.

USAGE
-----
Once installed and setup, you can use drush as follows while in
any Drupal directory:

  $ drush [options] <command> [argument1] [argument2]

Use the 'help' command to get a list of available options and commands:

  $ drush help

For even more documentation, use the 'topic' command:

  $ drush topic

For multisite installations, you might need to use the -l or other command line
options just to get drush to work:

  $ drush -l http://example.com help

Related Options:
  -r <path>, --root=<path>      Drupal root directory to use
                                (default: current directory or anywhere in a Drupal directory tree)
  -l <uri> , --uri=<uri>        URI of the drupal site to use
                                (only needed in multisite environments)
  -v, --verbose                 Display verbose output.
  --php                         The absolute path to your php binary.

NOTE: If you do not specify a URI with -l and drush falls back to the default
site configuration, Drupal's $GLOBAL['base_url'] will be set to http://default.
This may cause some functionality to not work as expected.

The drush core-cli command provide a customized bash shell or lets you enhance
your usual shell with its --pipe option.

Many commands support a --pipe option which returns machine readable output. See
`drush pm-list --status=enabled --pipe` as an example.

Very intensive scripts can exhaust your available PHP memory. One remedy is to 
just restart automatically using bash. For example:

    while true; do drush search-index; sleep 5; done

EXAMPLES
--------
Inside the "examples" folder you will find some example files to help you
get started with your drush configuration file (example.drushrc.php),
site alias definitions (example.aliases.drushrc.php) and drush commands
(sandwich.drush.inc). You will also see an example 'policy' file which 
can be customized to block certain commands or arguments as your organization
needs.

DRUSHRC.PHP
--------
If you get tired of typing options all the time, you can add them to your drush.php alias or
create a drushrc.php file. These provide additional options for your drush call. They provide
great flexibility for a multi-site installation, for example. See example.drushrc.php.

SITE ALIASES
--------
Drush lets you run commands on a remote server, or even on a set of remote servers.
See http://drupal.org/node/670460 and example.aliases.drushrc.php for more information.

COMMANDS
--------
Drush ships with a number of commands, but you can easily write
your own. In fact, writing a drush command is no harder than writing simple
Drupal modules, since drush command files closely follow the structure of
ordinary Drupal modules.

See sandwich.drush.inc for light details on the internals of a drush command file.
Otherwise, the core commands in drush are good models for your own commands.

You can put your drush command file in a number of places:

  - In a folder specified with the --include option (see `drush topic docs-configuration`).
  - Along with one of your existing modules. If your command is related to an
    existing module, this is the preferred approach.
  - In a .drush folder in your HOME folder. Note, that you have to create the
    .drush folder yourself.
  - In the system-wide drush commands folder, e.g. /usr/share/drush/commands

In any case, it is important that you end the filename with ".drush.inc", so
that drush can find it.

FAQ
---
  Q: What does "drush" stand for?
  A: The Drupal Shell.

  Q: How do I pronounce drush?
  A: Some people pronounce the dru with a long u like drupal. Fidelity points go to
  them, but they are in the minority. Most pronounce drush so that it rhymes with
  hush, rush, flush, etc. This is the preferred pronunciation.

CREDITS
-------
Originally developed by Arto Bendiken <http://bendiken.net/> for Drupal 4.7.
Redesigned by Franz Heinzmann (frando) <http://unbiskant.org/> in May 2007 for Drupal 5.
Maintained by Moshe Weitzman <http://drupal.org/moshe> with much help from
Owen Barton, Adrian Rossouw, greg.1.anderson, jonhattan.

File

README.txt
View source
  1. DESCRIPTION
  2. -----------
  3. Drush is a command line shell and Unix scripting interface for Drupal.
  4. If you are unfamiliar with shell scripting, reviewing the documentation
  5. for your shell (e.g. man bash) or reading an online tutorial (e.g. search
  6. for "bash tutorial") will help you get the most out of Drush.
  7. Drush core ships with lots of useful commands for interacting with code
  8. like modules/themes/profiles. Similarly, it runs update.php, executes sql
  9. queries and DB migrations, and misc utilities like run cron or clear cache.
  10. REQUIREMENTS
  11. ------------
  12. * To use drush from the command line, you'll need a CLI-mode capable PHP
  13. binary. The minimum PHP version is 5.2.
  14. * Drush 4 does not support Windows; see "For Windows", below.
  15. * Drush works with Drupal 5, Drupal 6 and Drupal 7. However, occasionally
  16. recent changes to the most recent version of Drupal can introduce issues
  17. with drush. On Drupal 5, drush requires update_status v5.x-2.5 or later
  18. in order to use pm-updatecode. If you have an earlier version of update_status,
  19. upgrade it via "drush dl update_status" before using pm-updatecode.
  20. INSTALLATION
  21. ------------
  22. For Linux/Unix/Mac:
  23. 1. Untar the tarball into a folder outside of your web site (/path/to/drush)
  24. (e.g. if drush is in your home directory, ~/drush can be used for /path/to/drush)
  25. 2. Make the 'drush' command executable:
  26. $ chmod u+x /path/to/drush/drush
  27. 3. (Optional, but recommended:) To ease the use of drush,
  28. - create a link to drush in a directory that is in your PATH, e.g.:
  29. $ ln -s /path/to/drush/drush /usr/local/bin/drush
  30. OR
  31. - add the folder that contains drush to your PATH
  32. PATH=$PATH:/path/to/drush
  33. This goes into .profile, .bash_aliases or .bashrc in your home folder.
  34. NOTE: You must log out and then log back in again or re-load your bash
  35. configuration file to apply your changes to your current session:
  36. $ source .bashrc
  37. NOTE FOR ADVANCED USERS
  38. - If you want to run drush with a specific version of php, rather than the
  39. one found by the drush command, you can define an environment variable
  40. DRUSH_PHP that points to the php to execute:
  41. export DRUSH_PHP=/usr/bin/php5
  42. OR
  43. - If you want to exactly control how drush is called, you may define an alias
  44. that executes the drush.php file directly and passes that path to drush:
  45. $ alias drush='/path/to/php/php5 -d memory_limit=128M /path/to/drush/drush.php --php="/path/to/php/php5 -d memory_limit=128M"'
  46. Note that it is necessary to pass the '--php' option to drush to define
  47. how drush should call php if it needs to do so.
  48. If you define an alias, to allow Drush to detect the number of available columns,
  49. you need to add the line 'export COLUMNS' to the .profile file in your
  50. home folder.
  51. NOTE ON PHP.INI FILES
  52. - Usually, php is configured to use separate php.ini files for the web server
  53. and the command line. To see which php.ini file drush is using, run:
  54. $ drush status
  55. - Compare the php.ini that drush is using with the php.ini that the webserver is
  56. using. Make sure that drush's php.ini is given as much memory to work with as
  57. the web server is; otherwise, Drupal might run out of memory when drush
  58. bootstraps it.
  59. - Drush requires a fairly unrestricted php environment to run in. In particular,
  60. you should insure that safe_mode, open_basedir, disable_functions and
  61. disable_classes are empty.
  62. - If drush is using the same php.ini file as the web server, you can create
  63. a php.ini file exclusively for drush by copying your web server's php.ini
  64. file to the folder $HOME/.drush or the folder /etc/drush. Then you may edit
  65. this file and change the settings described above without affecting the
  66. php enviornment of your web server. Alternately, if you only want to
  67. override a few values, copy example.drush.ini from the "examples" folder
  68. into $HOME/.drush or the folder /etc/drush and edit to suit. See comments
  69. in example.drush.ini for more details.
  70. 4. Start using drush by running "drush" from your Drupal root directory.
  71. (or, if you did not follow step 3, by running "/path/to/drush/drush"
  72. or navigating to /path/to/drush and running "./drush" )
  73. If you have troubles, try using the -l and -r options when invoking drush. See below.
  74. For Windows:
  75. - Drush 4 does not support Windows. Consider using Drush 3 or Drush 5 instead.
  76. - Consider using on Linux/Unix/OSX using Virtualbox or other VM. Windows support is lacking.
  77. - The Drush 5 Windows installer can be found at http://drush.ws/drush_windows_installer.
  78. - Instructions for installing Drush 3 on Windows can be found at
  79. http://drupal.org/node/594744.
  80. USAGE
  81. -----
  82. Once installed and setup, you can use drush as follows while in
  83. any Drupal directory:
  84. $ drush [options] <command> [argument1] [argument2]
  85. Use the 'help' command to get a list of available options and commands:
  86. $ drush help
  87. For even more documentation, use the 'topic' command:
  88. $ drush topic
  89. For multisite installations, you might need to use the -l or other command line
  90. options just to get drush to work:
  91. $ drush -l http://example.com help
  92. Related Options:
  93. -r <path>, --root=<path> Drupal root directory to use
  94. (default: current directory or anywhere in a Drupal directory tree)
  95. -l <uri> , --uri=<uri> URI of the drupal site to use
  96. (only needed in multisite environments)
  97. -v, --verbose Display verbose output.
  98. --php The absolute path to your php binary.
  99. NOTE: If you do not specify a URI with -l and drush falls back to the default
  100. site configuration, Drupal's $GLOBAL['base_url'] will be set to http://default.
  101. This may cause some functionality to not work as expected.
  102. The drush core-cli command provide a customized bash shell or lets you enhance
  103. your usual shell with its --pipe option.
  104. Many commands support a --pipe option which returns machine readable output. See
  105. `drush pm-list --status=enabled --pipe` as an example.
  106. Very intensive scripts can exhaust your available PHP memory. One remedy is to
  107. just restart automatically using bash. For example:
  108. while true; do drush search-index; sleep 5; done
  109. EXAMPLES
  110. --------
  111. Inside the "examples" folder you will find some example files to help you
  112. get started with your drush configuration file (example.drushrc.php),
  113. site alias definitions (example.aliases.drushrc.php) and drush commands
  114. (sandwich.drush.inc). You will also see an example 'policy' file which
  115. can be customized to block certain commands or arguments as your organization
  116. needs.
  117. DRUSHRC.PHP
  118. --------
  119. If you get tired of typing options all the time, you can add them to your drush.php alias or
  120. create a drushrc.php file. These provide additional options for your drush call. They provide
  121. great flexibility for a multi-site installation, for example. See example.drushrc.php.
  122. SITE ALIASES
  123. --------
  124. Drush lets you run commands on a remote server, or even on a set of remote servers.
  125. See http://drupal.org/node/670460 and example.aliases.drushrc.php for more information.
  126. COMMANDS
  127. --------
  128. Drush ships with a number of commands, but you can easily write
  129. your own. In fact, writing a drush command is no harder than writing simple
  130. Drupal modules, since drush command files closely follow the structure of
  131. ordinary Drupal modules.
  132. See sandwich.drush.inc for light details on the internals of a drush command file.
  133. Otherwise, the core commands in drush are good models for your own commands.
  134. You can put your drush command file in a number of places:
  135. - In a folder specified with the --include option (see `drush topic docs-configuration`).
  136. - Along with one of your existing modules. If your command is related to an
  137. existing module, this is the preferred approach.
  138. - In a .drush folder in your HOME folder. Note, that you have to create the
  139. .drush folder yourself.
  140. - In the system-wide drush commands folder, e.g. /usr/share/drush/commands
  141. In any case, it is important that you end the filename with ".drush.inc", so
  142. that drush can find it.
  143. FAQ
  144. ---
  145. Q: What does "drush" stand for?
  146. A: The Drupal Shell.
  147. Q: How do I pronounce drush?
  148. A: Some people pronounce the dru with a long u like drupal. Fidelity points go to
  149. them, but they are in the minority. Most pronounce drush so that it rhymes with
  150. hush, rush, flush, etc. This is the preferred pronunciation.
  151. CREDITS
  152. -------
  153. Originally developed by Arto Bendiken <http://bendiken.net/> for Drupal 4.7.
  154. Redesigned by Franz Heinzmann (frando) <http://unbiskant.org/> in May 2007 for Drupal 5.
  155. Maintained by Moshe Weitzman <http://drupal.org/moshe> with much help from
  156. Owen Barton, Adrian Rossouw, greg.1.anderson, jonhattan.