first import

sites/all/modules/drush/docs/shellscripts.html

@@ -0,0 +1,80 @@
+<h1>The Drush Shell Scripts</h1>
+<p>
+A drush shell script is any Unix shell script file that has
+its "execute" bit set (i.e., via `chmod +x myscript.drush`)
+and that begins with a specific line:
+<pre>
+	#!/usr/bin/env drush
+</pre>
+ - or -
+<pre> 
+	#!/full/path/to/drush
+</pre><p>
+The former is the usual form, and is more convenient in that
+it will allow you to run the script regardless of where drush
+has been installed on your system, as long as it appears in
+your PATH.  The later form allows you to specify the drush
+command add options to use, as in:
+<pre>
+	#!/full/path/to/drush php-script --some-option
+</pre><p>
+Adding specific options is important only in certain cases,
+described later; it is usually not necessary.
+<p>
+Drush scripts do not need to be named "*.drush" or "*.script";
+they can be named anything at all.  To run them, make sure they 
+are executable (`chmod +x helloworld.script`) and then run them 
+from the shell like any other script.
+<p>
+There are two big advantages to drush scripts over bash scripts:
+<ul>
+<li>They are written in php
+
+<li>drush can bootstrap your Drupal site before
+    running your script.
+</ul><p>
+To bootstrap a Drupal site, provide an alias to the site to 
+bootstrap as the first commandline argument.
+<p>
+For example:
+<pre>
+	$ helloworld.script @dev a b c
+</pre><p>
+If the first argument is a valid site alias, drush will remove 
+it from the arument list and bootstrap that site, then run
+your script.  The script itself will not see @dev on its
+argument list.  If you do not want drush to remove the first
+site alias from your scripts argument list (e.g. if your script
+wishes to syncronise two sites, specified by the first two
+arguments, and does not want to bootstrap either of those
+two sites), then fully specify the drush command (php-script)
+and options to use, as shown above.  By default, if the drush
+command is not specified, drush will provide the following default
+line:
+<pre>
+	#!/full/path/to/drush php-script --bootstrap-to-first-arg
+</pre><p>
+It is the option --bootstrap-to-first-arg that causes drush to
+pull off the first argument and bootstrap it.  The way to get rid
+of that option is to specify the php-script line to run, and leave
+it off, like so:
+<pre>
+	#!/full/path/to/drush php-script
+</pre><p>
+Note that 'php-script' is the only built-in drush command that
+makes sense to put on the "shebang" ("#!" is pronounced "shebang")
+line.  However, if you wanted to, you could implement your own
+custom version of php-script (e.g. to preprocess the script input,
+perhaps), and specify that command on the shebang line.
+<p>
+Drush scripts can access their arguments via the drush_shift()
+function:
+<pre>
+        while ($arg = drush_shift()) {
+          drush_print($arg);
+        }
+</pre><p>
+Options are available via drush_get_option('option-name').
+<p>
+See the example drush script in `drush topic docs-examplescript`,
+and the list of drush error codes in `drush topic docs-errorcodes`.