Skip to content

Commit

Permalink
Switch to Markdown format
Browse files Browse the repository at this point in the history
  • Loading branch information
@weitzman
weitzman committed Aug 18, 2013
1 parent 5db2b32 commit 9a1a9ce
Showing 1 changed file with 67 additions and 70 deletions.
137 changes: 67 additions & 70 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Drush is a command line shell and Unix scripting interface for Drupal. If you a

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.

To contribute to Drush, see /CONTRIBUTING.md
To contribute to Drush, see [/CONTRIBUTING.md](CONTRIBUTING.md)

REQUIREMENTS
============
Expand All @@ -27,11 +27,11 @@ A common way to install Drush is via our PEAR channel. See instructions at http:
`$ ln -s /path/to/drush/drush /usr/bin/drush`

1. Configure your system to recognize where Drush resides. There are 2 options:
1. create a symbolic link to the Drush executable in a directory that is already in your PATH, e.g.:
1. 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`

1. 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.:
1. 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"`

Expand All @@ -42,43 +42,45 @@ A common way to install Drush is via our PEAR channel. See instructions at http:

`$ 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).
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).

1. Test that Drush is found by your system:

`$ which drush`

1. Optional. Help the Drush development team by sending anonymized usage statistics. To automatically send usage data, please add the following to a .drushrc.php file:

`$options['drush_usage_log'] = TRUE;`
`$options['drush_usage_send'] = TRUE;`
```php
$options['drush_usage_log'] = TRUE;
$options['drush_usage_send'] = TRUE;
```

Stats are usually logged locally and sent whenever log file exceeds 50Kb.
Alternatively, one may disable automatic sending and instead use usage-view
and usage-send commands to more carefully send data.

1. Optional. See examples/example.bashrc for instructions on how to add some
1. Optional. See [example.bashrc](examples/example.bashrc) for instructions on how to add some
useful shell aliases that provides even tighter integration between
drush and bash. You may source this file directly into your shell by adding to
your .bashrc (or equivalent): source /path/to/drush/examples/example.bashrc

1. Optional. If you didn't source it in Step 6 above, see top of
drush.complete.sh file for instructions adding bash completion for drush
[drush.complete.sh](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.

1. Optional. If drush.complete.sh is being sourced (ideally in
1. Optional. If [drush.complete.sh](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:

```bash
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]$
`msonnabaum@hostname ~/repos/drush (master)[@sitename]$`

ADDITIONAL CONFIGURATIONS FOR MAMP:
-----------------------------------
Expand All @@ -90,22 +92,24 @@ if it does not already exist) a file called .bash_profile in your home folder.

To use php 5.3.x, add this line to .bash_profile:

export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5.3/bin:$PATH"
export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5.3/bin:$PATH"

If you want to use php 5.4.x, add this line instead:

export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5.4/bin:$PATH"
export PATH="/Applications/MAMP/Library/bin:/Applications/MAMP/bin/php5.4/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"
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:

```bash
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
Expand All @@ -119,22 +123,21 @@ 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)
Path|Application
-----|----
/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
- - - - - - - - - - - - - - - - - - - - - - -
RUNNING A SPECIFIC PHP 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
php defined by your shell, 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:
Expand All @@ -150,7 +153,7 @@ Drush bootstraps it.

To see which php.ini file Drush is using, run:

$ drush status
$ 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.
Expand All @@ -161,18 +164,18 @@ 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
Alternately, if you only want to override a few values, copy [example.drush.ini](examples/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.
You may also use environment variables to control the php settings that Drush
will use. There are three options:
export PHP_INI='/path/to/php.ini'

export DRUSH_INI='/path/to/drush.ini'

export PHP_OPTIONS='-d memory_limit="128M"'
```bash
export PHP_INI='/path/to/php.ini'
export DRUSH_INI='/path/to/drush.ini'
export PHP_OPTIONS='-d memory_limit="128M"'
```
In the case of PHP_INI and DRUSH_INI, these environment variables specify the
full path to a php.ini or drush.ini file, should you wish to use one that is
Expand All @@ -185,20 +188,19 @@ you should insure that safe_mode, open_basedir, disable_functions and
disable_classes are empty. If you are using php 5.3.x, you may also need to
add the following definitions to your php.ini file:
```ini
magic_quotes_gpc = Off
magic_quotes_runtime = Off
magic_quotes_sybase = Off

```
INSTALLING DRUSH ON WINDOWS:
----------------------------
Windows support has improved, but is still lagging. For full functionality,
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.
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.
Expand All @@ -219,30 +221,29 @@ information presented in the example.aliases.drushrc.php file, especially when
setting values for 'remote-host' and 'os', as these are very important when
running Drush rsync and Drush sql-sync commands.


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]
$ drush [options] <command> [argument1] [argument2]

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

$ drush help
$ drush help

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

$ drush topic
$ drush topic

For a full list of Drush commands and documentation by version, visit
http://www.drush.org.

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
$ 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
Expand All @@ -251,25 +252,27 @@ command line options just for Drush to work. If you do not specify a URI with
$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
$ 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
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
Inside the [examples](examples) directory 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
Expand All @@ -282,7 +285,7 @@ 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
multi-site installation. See [example.drushrc.php](examples/example.drushrc.php) for examples and installation
details.

SITE ALIASES
Expand All @@ -291,40 +294,33 @@ 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.

# Synchronize 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
```bash
# Synchronize 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
See http://drupal.org/node/670460 and [example.aliases.drushrc.php](examples/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.
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.
See [sandwich.drush.inc](examples/sandwich.drush.inc) for a quick tutorial arounda 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
1. 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
1. 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
1. 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 /drush or sites/all/drush folders. Note, that you have to create the
1. In the system-wide Drush commands folder, e.g. /usr/share/drush/commands.
1. In Drupal's /drush or sites/all/drush folders. 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
Expand All @@ -334,6 +330,7 @@ that Drush can find it.
FAQ
===
```
Q: What does "drush" stand for?
A: The Drupal Shell.
Expand All @@ -345,12 +342,12 @@ FAQ
Q: Does Drush have unit tests?
A: Drush has an excellent suite of unit tests. See the README.txt file in the /tests subdirectory for
more information.

```
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
* Originally developed by [Arto Bendiken](http://bendiken.net) for Drupal 4.7.
* Redesigned by [Franz Heinzmann](http://unbiskant.org) in May 2007 for Drupal 5.
* Maintained by [Moshe Weitzman](http://drupal.org/moshe) with much help from
Owen Barton, greg.1.anderson, jonhattan, Mark Sonnabaum, and Jonathan Hedstrom.

0 comments on commit 9a1a9ce

Please sign in to comment.