prepare for RC2.
[project/drush.git] / README.txt
1
2 DESCRIPTION
3 ===========
4
5 Drush is a command line shell and Unix scripting interface for Drupal.  If you
6 are unfamiliar with shell scripting, reviewing the documentation for your shell
7 (e.g. man bash) or reading an online tutorial (e.g. search for "bash tutorial")
8 will help you get the most out of Drush.
9
10 Drush core ships with lots of useful commands for interacting with code like
11 modules/themes/profiles. Similarly, it runs update.php, executes sql queries
12 and DB migrations, and misc utilities like run cron or clear cache.
13
14
15 REQUIREMENTS
16 ============
17
18 * To use Drush from the command line, you'll need a CLI-mode capable PHP binary
19   version 5.2 or greater.
20
21 * Drush commands that work with git require git 1.7 or greater.
22
23 * Drush is designed for a Unix-like OS (Linux, OS X)
24
25 * Most Drush commands run on Windows.  See INSTALLING DRUSH ON WINDOWS, below.
26
27 * Drush works with Drupal 6, Drupal 7, and usually Drupal 8.
28
29
30 INSTALLATION
31 ============
32
33 The preferred way to install Drush is via our PEAR channel. See instructions at
34 http://drupal.org/project/drush. If you prefer a more manual install, see
35 below.
36
37 1. Place the uncompressed drush.tar.gz, drush.zip, or cloned git repository in
38    a directory that is outside of your web root.
39
40 2. Make the 'drush' command executable:
41
42      $ chmod u+x /path/to/drush/drush
43
44 3. Configure your system to recognize where Drush resides. There are 2 options:
45
46   a) create a symbolic link to the Drush executable in a directory that is
47      already in your PATH, e.g.:
48
49        $ ln -s /path/to/drush/drush /usr/bin/drush
50
51   b) explicitly add the Drush executable to the PATH variable which is defined
52      in the the shell configuration file called .profile, .bash_profile,
53      .bash_aliases, or .bashrc that is located in your home folder, i.e.:
54
55        export PATH="$PATH:/path/to/drush:/usr/local/bin"
56
57      Your system will search path options from left to right until it finds a
58      result.
59
60      To apply your changes to your current session, either log out and then log
61      back in again, or re-load your bash configuration file, i.e.:
62
63        $ source .bashrc
64
65   NOTE: If you do not follow step 3, you will need to inconveniently run Drush
66   commands using the full path to the executable "/path/to/drush/drush" or by
67   navigating to /path/to/drush and running "./drush". The -r or -l options will
68   be required (see USAGE, below).
69
70 4. Test that Drush is found by your system:
71
72   $ which drush
73
74 5. Optional. Help the Drush development team by sending anonymized usage
75    statistics.  To automatically send usage data, please add the following to a
76    .drushrc.php file:
77
78      $options['drush_usage_log'] = TRUE;
79      $options['drush_usage_send'] = TRUE;
80
81    Stats are usually logged locally and sent whenever log file exceeds 50Kb.
82    Alternatively, one may disable automatic sending and instead use usage-view
83    and usage-send commands to more carefully send data.
84
85 6. Optional. See examples/example.bashrc for instructions on how to add some
86    useful shell aliases that provides even tighter integration between
87    drush and bash.
88
89 7. Optional. If you didn't source it in Step 5 above, see top of
90    drush.complete.sh file for instructions adding bash completion for drush
91    command to your shell.  Once configured, completion works for site aliases,
92    command names, shell aliases, global options, and command-specific options.
93
94 8. Optional. If drush.complete.sh is being sourced (ideally in
95    bash_completion.d), you can use the supplied __drush_ps1() sh function to
96    add your current drush site (set with `drush use @sitename`) to your PS1
97    prompt like so:
98
99       if [ "\$(type -t __git_ps1)" ] && [ "\$(type -t __drush_ps1)" ]; then
100         PS1='\u@\h \w$(__git_ps1 " (%s)")$(__drush_ps1 "[%s]")\$ '
101       fi
102
103    Putting this in a .bashrc/.bash_profile/.profile would produce this prompt:
104
105      msonnabaum@hostname ~/repos/drush (master)[@sitename]$
106
107 ADDITIONAL CONFIGURATIONS FOR MAMP:
108 -----------------------------------
109
110 Users of MAMP will need to manually specify in their PATH which version of php
111 and MySQL to use in the command line interface. This is independent of the php
112 version selected in the MAMP application settings.  Under OS X, edit (or create
113 if it does not already exist) a file called .bash_profile in your home folder.
114
115 To use php 5.2.x, add this line to .bash_profile:
116
117   export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5.2/bin:$PATH"
118
119 If you want to use php 5.3.x, add this line instead:
120
121   export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5.3/bin:$PATH"
122
123 If you have MAMP v.1.84 or lower, this configuration will work for both version
124 of PHP:
125
126   export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5/bin:$PATH"
127
128 If you have done this and are still getting a "no such file or directory" error
129 from PDO::__construct, try this:
130
131   sudo mkdir /var/mysql
132   sudo ln -s /Applications/MAMP/tmp/mysql/mysql.sock /var/mysql/mysql.sock
133
134 Additionally, you may need to adjust your php.ini settings before you can use
135 drush successfully. See CONFIGURING PHP.INI below for more details on how to
136 proceed.
137
138 ADDITIONAL CONFIGURATIONS FOR OTHER AMP STACKS:
139 -----------------------------------------------
140
141 Users of other Apache distributions such as XAMPP, or Acquia's Dev Desktop will
142 want to ensure that its php can be found by the command line by adding it to
143 the PATH variable, using the method in 3.b above. Depending on the version and
144 distribution of your AMP stack, PHP might reside at:
145
146   /Applications/acquia-drupal/php/bin   Acquia Dev Desktop (Mac)
147   /Applications/xampp/xamppfiles/bin    XAMP (Mac)
148   /opt/lampp/bin                        XAMPP (Windows)
149
150 Additionally, you may need to adjust your php.ini settings before you can use
151 drush successfully. See CONFIGURING PHP.INI below for more details on how to
152 proceed.
153
154 CUSTOM CONFIGURATIONS:
155 ----------------------
156
157 Running a specific php-cli version for Drush
158 - - - - - - - - - - - - - - - - - - - - - - -
159
160   If you want to run Drush with a specific version of php, rather than the
161   php-cli defined by your system, you can add an environment variable to your
162   the shell configuration file called .profile, .bash_profile, .bash_aliases,
163   or .bashrc that is located in your home folder:
164
165     export DRUSH_PHP='/path/to/php'
166
167 CONFIGURING PHP.INI
168 -------------------
169
170 Usually, php is configured to use separate php.ini files for the web server and
171 the command line. Make sure that Drush's php.ini is given as much memory to
172 work with as the web server is; otherwise, Drupal might run out of memory when
173 Drush bootstraps it.
174
175 To see which php.ini file Drush is using, run:
176
177   $ drush status
178
179 To see which php.ini file the webserver is using, use the phpinfo() function in
180 a .php web page.  See http://drupal.org/node/207036.
181
182 If Drush is using the same php.ini file as the web server, you can create a
183 php.ini file exclusively for Drush by copying your web server's php.ini file to
184 the folder $HOME/.drush or the folder /etc/drush.  Then you may edit this file
185 and change the settings described above without affecting the php enviornment
186 of your web server.
187
188 Alternately, if you only want to override a few values, copy example.drush.ini
189 from the "examples" folder into $HOME/.drush or the folder /etc/drush and edit
190 to suit.  See comments in example.drush.ini for more details.
191
192 Drush requires a fairly unrestricted php environment to run in.  In particular,
193 you should insure that safe_mode, open_basedir, disable_functions and
194 disable_classes are empty.
195
196 INSTALLING DRUSH ON WINDOWS:
197 ----------------------------
198
199 Windows support has improved, but is still lagging. Consider using on
200 Linux/Unix/OSX using Virtualbox or other virtual machine.
201
202 There is a Windows msi installer for drush available at:
203
204   http://www.drush.org/drush_windows_installer.
205
206 Please see that page for more information on running Drush on Windows.
207
208 Whenever the documentation or the help text refers to 'drush [option]
209 <command>' or something similar, 'drush' may need to be replaced by
210 'drush.bat'.
211
212 Additional Drush Windows installation documentation can be found at
213 http://drupal.org/node/594744.
214
215
216 USAGE
217 =====
218
219 Once you have completed the installation steps, Drush can be run in your shell
220 by typing "drush" from within any Drupal root directory.
221
222   $ drush [options] <command> [argument1] [argument2]
223
224 Use the 'help' command to get a list of available options and commands:
225
226   $ drush help
227
228 For even more documentation, use the 'topic' command:
229
230   $ drush topic
231
232 For a full list of Drush commands and documentation by version, visit
233 http://drush.ws.
234
235 Many commands support a --pipe option which returns machine readable output.
236 For example, return a list of enabled modules:
237
238   $ drush pm-list --type=module --status=enabled --pipe
239
240 For multisite installations, use the -l option to target a particular site.  If
241 you are outside the Drupal web root, you might need to use the -r, -l or other
242 command line options just for Drush to work. If you do not specify a URI with
243 -l and Drush falls back to the default site configuration, Drupal's
244 $GLOBAL['base_url'] will be set to http://default.  This may cause some
245 functionality to not work as expected.
246
247   $ drush -l http://example.com pm-update
248
249 Related Options:
250   -r <path>, --root=<path>      Drupal root directory to use
251                                 (defaults to current directory or anywhere in a
252                                 Drupal directory tree)
253   -l <uri> , --uri=<uri>        URI of the Drupal site to use
254   -v, --verbose                 Display verbose output.
255
256 Very intensive scripts can exhaust your available PHP memory. One remedy is to
257 just restart automatically using bash. For example:
258
259   while true; do drush search-index; sleep 5; done
260
261
262 DRUSH CONFIGURATION FILES
263 =========================
264
265 Inside /path/to/drush/examples you will find some example files to help you get
266 started with your Drush configuration file (example.drushrc.php), site alias
267 definitions (example.aliases.drushrc.php) and Drush commands
268 (sandwich.drush.inc). You will also see an example 'policy' file which can be
269 customized to block certain commands or arguments as required by your
270 organization's needs.
271
272 DRUSHRC.PHP
273 -----------
274
275 If you get tired of typing options all the time you can contain them in a
276 drushrc.php file. Multiple Drush configuration files can provide the
277 flexibility of providing specific options in different site directories of a
278 multi-site installation. See example.drushrc.php for examples and installation
279 details.
280
281 SITE ALIASES
282 ------------
283
284 Drush lets you run commands on a remote server, or even on a set of remote
285 servers.  Once defined, aliases can be references with the @ nomenclature, i.e.
286
287   # Syncronize staging files to production
288   $ drush rsync @staging:%files/ @live:%files
289
290   # Syncronize database from production to dev, excluding the cache table
291   $ drush sql-sync --structure-tables-key=custom --no-cache @live @dev
292
293 See http://drupal.org/node/670460 and example.aliases.drushrc.php for more
294 information.
295
296 COMMANDS
297 --------
298
299 Drush can be extended to run your own commands. Writing a Drush command is no
300 harder than writing simple Drupal modules, since they both follow the same
301 structure.
302
303 See examples/sandwich.drush.inc for light details on the internals of a Drush
304 command file.  Otherwise, the core commands in Drush are good models for your
305 own commands.
306
307 You can put your Drush command file in a number of places:
308
309   a) In a folder specified with the --include option (see `drush topic
310      docs-configuration`).
311
312   b) Along with one of your enabled modules. If your command is related to an
313      existing module, this is the preferred approach.
314
315   c) In a .drush folder in your HOME folder. Note, that you have to create the
316      .drush folder yourself.
317
318   d) In the system-wide Drush commands folder, e.g. /usr/share/drush/commands.
319
320   e) In Drupal's sites/all/drush folder. Note, that you have to create the
321      drush folder yourself.
322
323 In any case, it is important that you end the filename with ".drush.inc", so
324 that Drush can find it.
325
326
327 FAQ
328 ===
329
330   Q: What does "drush" stand for?
331   A: The Drupal Shell.
332
333   Q: How do I pronounce Drush?
334   A: Some people pronounce the dru with a long u like Drupal. Fidelity points
335      go to them, but they are in the minority. Most pronounce Drush so that it
336      rhymes with hush, rush, flush, etc. This is the preferred pronunciation.
337
338
339 CREDITS
340 =======
341
342 * Originally developed by Arto Bendiken <http://bendiken.net/> for Drupal 4.7.
343 * Redesigned by Franz Heinzmann (frando) <http://unbiskant.org/> in May 2007 for Drupal 5.
344 * Maintained by Moshe Weitzman <http://drupal.org/moshe> with much help from
345   Owen Barton, greg.1.anderson, jonhattan, Mark Sonnabaum, and Jonathan Hedstrom.