forked from drush-ops/drush
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.txt
312 lines (212 loc) · 12 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
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 version 5.2 or greater.
* Drush commands that work with git require git 1.7 or greater.
* Drush is designed for a Unix-like OS (Linux, OS X)
* Some Drush commands run on Windows. See INSTALLING DRUSH ON WINDOWS, below.
* Drush works with Drupal 6, Drupal 7, and Drupal 8. However, occasionally
recent changes to the most recent version of Drupal can introduce issues
with Drush.
INSTALLATION
============
The preferred way to install Drush is via our PEAR channel. See
instructions at http://drupal.org/project/drush. If you prefer a more manual
install, see below.
1. Place the uncompressed drush.tar.gz, drush.zip, or cloned git repository
in a directory that is outside of your web root.
2. Make the 'drush' command executable:
$ chmod u+x /path/to/drush/drush
3. Configure your system to recognize where Drush resides. There are 2 options:
a) create a symbolic link to the Drush executable in a directory that is already in your PATH, e.g.:
$ ln -s /path/to/drush/drush /usr/bin/drush
b) explicitly add the Drush executable to the PATH variable which is defined
in the the shell configuration file called .profile, .bash_profile, .bash_aliases, or .bashrc
that is located in your home folder, i.e.
export PATH="$PATH:/path/to/drush:/usr/local/bin"
(your system will search path options from left to right until it finds a result)
To apply your changes to your current session, either log out and then log back in again,
or re-load your bash configuration file, i.e.:
$ source .bashrc
NOTE: If you do not follow step 3, you will need to inconveniently run Drush commands using
the full path to the executable "/path/to/drush/drush" or by navigating to /path/to/drush
and running "./drush". The -r or -l options will be required (see USAGE, below).
4. Test that Drush is found by your system:
$ which drush
5. Optional. See examples/example.bashrc for instructions on how to add some very useful
shell aliases that provides even tighter integration between drush and bash.
6. Optional. If you didn't source it in Step 5 above, see top of drush.complete.sh
file for instructions adding bash completion for drush command to your shell.
Once configured, completion works for site aliases, command names, shell aliases,
global options, and command-specific options.
7. Optional. If drush.complete.sh is being sourced (ideally in bash_completion.d),
you can use the supplied __drush_ps1() sh function to add your current drush
site (set with `drush use @sitename`) to your PS1 prompt like so:
if [ "\$(type -t __git_ps1)" ] && [ "\$(type -t __drush_ps1)" ]; then
PS1='\u@\h \w$(__git_ps1 " (%s)")$(__drush_ps1 "[%s]")\$ '
fi
Putting this in a .bashrc/.bash_profile/.profile would produce this
prompt:
msonnabaum@hostname ~/repos/drush (master)[@sitename]$
ADDITIONAL CONFIGURATIONS FOR MAMP:
-----------------------------------
Users of MAMP will need to manually specify in their PATH which version
of php and MySQL to use in the command line interface. This is independent of the php
version selected in the MAMP application settings.
Under OS X, edit (or create if it does not already exist) a file called .bash_profile
in your home folder.
To use php 5.2.x, add this line to .bash_profile:
export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5.2/bin:$PATH"
If you want to use php 5.3.x, add this line instead
export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5.3/bin:$PATH"
If you have MAMP v.1.84 or lower, this configuration will work for both version of php:
export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5/bin:$PATH"
If you have done this and are still getting a "no such file or directory" error from
PDO::__construct, try this:
sudo mkdir /var/mysql
sudo ln -s /Applications/MAMP/tmp/mysql/mysql.sock /var/mysql/mysql.sock
Additionally, you may need to adjust your php.ini settings before you can use
drush successfully. See CONFIGURING PHP.INI below for more details on how to proceed.
ADDITIONAL CONFIGURATIONS FOR OTHER AMP STACKS:
-----------------------------------------------
Users of other Apache distributions such as XAMPP, or Acquia's Dev Desktop
will want to ensure that its php can be found by the command line by adding
it to the PATH variable, using the method in 3.b above. Depending on the
version and distribution of your AMP stack, php might reside at:
/Applications/acquia-drupal/php/bin Acquia Dev Desktop (Mac)
/Applications/xampp/xamppfiles/bin XAMP (Mac)
/opt/lampp/bin XAMPP (Windows)
Additionally, you may need to adjust your php.ini settings before you can use
drush successfully. See CONFIGURING PHP.INI below for more details on how to proceed.
CUSTOM CONFIGURATIONS:
----------------------
Running a specific php-cli version for Drush
- - - - - - - - - - - - - - - - - - - - - - -
If you want to run Drush with a specific version of php, rather than the
php-cli defined by your system, you can add an environment variable to your
the shell configuration file called .profile, .bash_profile, .bash_aliases, or .bashrc
that is located in your home folder:
export DRUSH_PHP='/path/to/php'
CONFIGURING PHP.INI
-------------------
Usually, php is configured to use separate php.ini files for the web server
and the command line. 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.
To see which php.ini file Drush is using, run:
$ drush status
To see which php.ini file the webserver is using, use the phpinfo() function
in a .php web page. See http://drupal.org/node/207036.
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.
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.
INSTALLING DRUSH ON WINDOWS:
----------------------------
Windows support is improving, but is still lacking! Consider using on
Linux/Unix/OSX using Virtualbox or other virtual machine.
There is a Windows msi installer for drush available at:
http://www.drush.org/drush_windows_installer.
Please see that page for more information on running Drush on Windows.
Whenever the documentation or the help text refers to
'drush [option] <command>' or something similar, 'drush' may need to be replaced by 'drush.bat'.
Additional Drush Windows installation documentation can be found at http://drupal.org/node/594744
USAGE
=====
Once you have completed the installation steps, Drush can be run in your shell
by typing "drush" from within any Drupal root 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 a full list of Drush commands and documentation by version, visit http://drush.ws
Many commands support a --pipe option which returns machine readable output.
For example, return a list of enabled modules:
$ drush pm-list --type=module --status=enabled --pipe
For multisite installations, use the -l option to target a particular site.
If you are outside the Drupal web root, you might need to use the -r, -l or
other command line options just for Drush to work. 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.
$ drush -l http://example.com pm-update
Related Options:
-r <path>, --root=<path> Drupal root directory to use
(defaults to current directory or anywhere in a Drupal directory tree)
-l <uri> , --uri=<uri> URI of the Drupal site to use
-v, --verbose Display verbose output.
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
DRUSH CONFIGURATION FILES
=========================
Inside /path/to/drush/examples 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 required by
your organization's needs.
DRUSHRC.PHP
-----------
If you get tired of typing options all the time you can contain them in a
drushrc.php file. Multiple Drush configuration files can provide the
flexibility of providing specific options in different site directories of a
multi-site installation. See example.drushrc.php for examples and installation
details.
SITE ALIASES
------------
Drush lets you run commands on a remote server, or even on a set of remote servers.
Once defined, aliases can be references with the @ nomenclature, i.e.
# Syncronize staging files to production
$ drush rsync @staging:%files/ @live:%files
# Syncronize database from production to dev, excluding the cache table
$ drush sql-sync --structure-tables-key=custom --no-cache @live @dev
See http://drupal.org/node/670460 and example.aliases.drushrc.php for more information.
COMMANDS
--------
Drush can be extended to run your own commands. Writing a Drush command is no harder
than writing simple Drupal modules, since they both follow the same structure.
See examples/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:
a) In a folder specified with the --include option (see `drush topic docs-configuration`).
b) Along with one of your enabled modules. If your command is related to an
existing module, this is the preferred approach.
c) In a .drush folder in your HOME folder. Note, that you have to create the
.drush folder yourself.
d) In the system-wide Drush commands folder, e.g. /usr/share/drush/commands
e) In Drupal's sites/all/drush folder. Note, that you have to create the
drush folder yourself.
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, Jonathan Hedstrom.