Back to dev
[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, you'll need a command line PHP version 5.3+.
19
20 * Drush commands that work with git require git 1.7 or greater.
21
22 * Drush works best on a Unix-like OS (Linux, OS X)
23
24 * Most Drush commands run on Windows.  See INSTALLING DRUSH ON WINDOWS, below.
25
26 * Drush 6 works with Drupal 6 or Drupal 7.
27
28
29 INSTALLATION
30 ============
31
32 A common way to install Drush is via our PEAR channel. See instructions at
33 http://drupal.org/project/drush. If you prefer a (slightly) more manual install, see
34 below.
35
36 1. Place the uncompressed drush.tar.gz, drush.zip, or cloned git repository in
37    a directory that is outside of your web root.
38
39 2. Make the 'drush' command executable:
40
41      $ chmod u+x /path/to/drush/drush
42
43 3. Configure your system to recognize where Drush resides. There are 2 options:
44
45   a) create a symbolic link to the Drush executable in a directory that is
46      already in your PATH, e.g.:
47
48        $ ln -s /path/to/drush/drush /usr/bin/drush
49
50   b) explicitly add the Drush executable to the PATH variable which is defined
51      in the the shell configuration file called .profile, .bash_profile,
52      .bash_aliases, or .bashrc that is located in your home folder, i.e.:
53
54        export PATH="$PATH:/path/to/drush:/usr/local/bin"
55
56      Your system will search path options from left to right until it finds a
57      result.
58
59      To apply your changes to your current session, either log out and then log
60      back in again, or re-load your bash configuration file, i.e.:
61
62        $ source .bashrc
63
64   NOTE: If you do not follow step 3, you will need to inconveniently run Drush
65   commands using the full path to the executable "/path/to/drush/drush" or by
66   navigating to /path/to/drush and running "./drush". The -r or -l options will
67   be required (see USAGE, below).
68
69 4. Test that Drush is found by your system:
70
71   $ which drush
72
73 5. Optional. Help the Drush development team by sending anonymized usage
74    statistics.  To automatically send usage data, please add the following to a
75    .drushrc.php file:
76
77      $options['drush_usage_log'] = TRUE;
78      $options['drush_usage_send'] = TRUE;
79
80    Stats are usually logged locally and sent whenever log file exceeds 50Kb.
81    Alternatively, one may disable automatic sending and instead use usage-view
82    and usage-send commands to more carefully send data.
83
84 6. Optional. See examples/example.bashrc for instructions on how to add some
85    useful shell aliases that provides even tighter integration between
86    drush and bash. You may source this file directly into your shell by adding to
87    your .bashrc (or equivalent): source /path/to/drush/examples/example.bashrc
88
89 7. Optional. If you didn't source it in Step 6 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.3.x, add this line to .bash_profile:
116
117   export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5.3/bin:$PATH"
118
119 If you want to use php 5.4.x, add this line instead:
120
121   export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5.4/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 You may also use environment variables to control the php settings that Drush
193 will use.  There are three options:
194
195     export PHP_INI='/path/to/php.ini'
196
197     export DRUSH_INI='/path/to/drush.ini'
198
199     export PHP_OPTIONS='-d memory_limit="128M"'
200
201 In the case of PHP_INI and DRUSH_INI, these environment variables specify the
202 full path to a php.ini or drush.ini file, should you wish to use one that is
203 not in one of the standard locations described above.  The PHP_OPTIONS
204 environment variable can be used to specify individual options that should
205 be passed to php on the command line when Drush is executed.
206
207 Drush requires a fairly unrestricted php environment to run in.  In particular,
208 you should insure that safe_mode, open_basedir, disable_functions and
209 disable_classes are empty.  If you are using php 5.3.x, you may also need to
210 add the following definitions to your php.ini file:
211
212 magic_quotes_gpc = Off
213 magic_quotes_runtime = Off
214 magic_quotes_sybase = Off
215
216
217 INSTALLING DRUSH ON WINDOWS:
218 ----------------------------
219
220 Windows support has improved, but is still lagging. For full functionality,
221 consider using on Linux/Unix/OSX using Virtualbox or other virtual machine.
222
223 There is a Windows msi installer for drush available at:
224
225   http://www.drush.org/drush_windows_installer.
226
227 Please see that page for more information on running Drush on Windows.
228
229 Whenever the documentation or the help text refers to 'drush [option]
230 <command>' or something similar, 'drush' may need to be replaced by
231 'drush.bat'.
232
233 Additional Drush Windows installation documentation can be found at
234 http://drupal.org/node/594744.
235
236 Most Drush commands will run in a Windows CMD shell or PowerShell, but the
237 Git Bash shell provided by the 'Git for Windows' installation is the preferred
238 shell in which to run Drush commands. For more information on "Git for Windows'
239 visit http://msysgit.github.com/.
240
241 When creating aliases for Windows remote machines, pay particular attention to
242 information presented in the example.aliases.drushrc.php file, especially when
243 setting values for 'remote-host' and 'os', as these are very important when
244 running Drush rsync and Drush sql-sync commands.
245
246
247 USAGE
248 =====
249
250 Once you have completed the installation steps, Drush can be run in your shell
251 by typing "drush" from within any Drupal root directory.
252
253   $ drush [options] <command> [argument1] [argument2]
254
255 Use the 'help' command to get a list of available options and commands:
256
257   $ drush help
258
259 For even more documentation, use the 'topic' command:
260
261   $ drush topic
262
263 For a full list of Drush commands and documentation by version, visit
264 http://www.drush.org.
265
266 Many commands support a --pipe option which returns machine readable output.
267 For example, return a list of enabled modules:
268
269   $ drush pm-list --type=module --status=enabled --pipe
270
271 For multisite installations, use the -l option to target a particular site.  If
272 you are outside the Drupal web root, you might need to use the -r, -l or other
273 command line options just for Drush to work. If you do not specify a URI with
274 -l and Drush falls back to the default site configuration, Drupal's
275 $GLOBAL['base_url'] will be set to http://default.  This may cause some
276 functionality to not work as expected.
277
278   $ drush -l http://example.com pm-update
279
280 Related Options:
281   -r <path>, --root=<path>      Drupal root directory to use
282                                 (defaults to current directory or anywhere in a
283                                 Drupal directory tree)
284   -l <uri> , --uri=<uri>        URI of the Drupal site to use
285   -v, --verbose                 Display verbose output.
286
287 Very intensive scripts can exhaust your available PHP memory. One remedy is to
288 just restart automatically using bash. For example:
289
290   while true; do drush search-index; sleep 5; done
291
292
293 DRUSH CONFIGURATION FILES
294 =========================
295
296 Inside /path/to/drush/examples you will find some example files to help you get
297 started with your Drush configuration file (example.drushrc.php), site alias
298 definitions (example.aliases.drushrc.php) and Drush commands
299 (sandwich.drush.inc). You will also see an example 'policy' file which can be
300 customized to block certain commands or arguments as required by your
301 organization's needs.
302
303 DRUSHRC.PHP
304 -----------
305
306 If you get tired of typing options all the time you can contain them in a
307 drushrc.php file. Multiple Drush configuration files can provide the
308 flexibility of providing specific options in different site directories of a
309 multi-site installation. See example.drushrc.php for examples and installation
310 details.
311
312 SITE ALIASES
313 ------------
314
315 Drush lets you run commands on a remote server, or even on a set of remote
316 servers.  Once defined, aliases can be references with the @ nomenclature, i.e.
317
318   # Synchronize staging files to production
319   $ drush rsync @staging:%files/ @live:%files
320
321   # Syncronize database from production to dev, excluding the cache table
322   $ drush sql-sync --structure-tables-key=custom --no-cache @live @dev
323
324 See http://drupal.org/node/670460 and example.aliases.drushrc.php for more
325 information.
326
327 COMMANDS
328 --------
329
330 Drush can be extended to run your own commands. Writing a Drush command is no
331 harder than writing simple Drupal modules, since they both follow the same
332 structure.
333
334 See examples/sandwich.drush.inc for light details on the internals of a Drush
335 command file.  Otherwise, the core commands in Drush are good models for your
336 own commands.
337
338 You can put your Drush command file in a number of places:
339
340   a) In a folder specified with the --include option (see `drush topic
341      docs-configuration`).
342
343   b) Along with one of your enabled modules. If your command is related to an
344      existing module, this is the preferred approach.
345
346   c) In a .drush folder in your HOME folder. Note, that you have to create the
347      .drush folder yourself.
348
349   d) In the system-wide Drush commands folder, e.g. /usr/share/drush/commands.
350
351   e) In Drupal's /drush or sites/all/drush folders. Note, that you have to create the
352      drush folder yourself.
353
354 In any case, it is important that you end the filename with ".drush.inc", so
355 that Drush can find it.
356
357
358 FAQ
359 ===
360
361   Q: What does "drush" stand for?
362   A: The Drupal Shell.
363
364   Q: How do I pronounce Drush?
365   A: Some people pronounce the dru with a long u like Drupal. Fidelity points
366      go to them, but they are in the minority. Most pronounce Drush so that it
367      rhymes with hush, rush, flush, etc. This is the preferred pronunciation.
368
369   Q: Does Drush have unit tests?
370   A: Drush has an excellent suite of unit tests. See the README.txt file in the /tests subdirectory for
371      more information.
372
373
374 CREDITS
375 =======
376
377 * Originally developed by Arto Bendiken <http://bendiken.net/> for Drupal 4.7.
378 * Redesigned by Franz Heinzmann (frando) <http://unbiskant.org/> in May 2007 for Drupal 5.
379 * Maintained by Moshe Weitzman <http://drupal.org/moshe> with much help from
380   Owen Barton, greg.1.anderson, jonhattan, Mark Sonnabaum, and Jonathan Hedstrom.