Simplify documentation for shell alias replacements

I'd really like to see this in drush-5 if possible. The code isn't hard if we can decide how it should work.

I think that replacing @self is dubious; there might be some cases where a literal '@self' is still desirable. Perhaps we should define a replacement {{%target}} or {{%target-site}} that evaluates to the alias provided before the command (or '@none' if none given).

The part that is not easily replicated is selecting your workflow on a per-site basis. You might push some sites with git, and just rsync others (scratch sites). I have some sites where I'd like to experiment with using Postgres journal files (postgres calls them something else) with point-in-time recovery instead of sql-dump / sql-sync (should be way faster for large databases). You might have some operations that you always want to perform when you pull stage down to dev (for example, turn on devel). If site-pull is a command with options, then it gets rather complicated as it slowly grows to meet all workflows. My thought is that you make commands like sql-sync and prepare-devsite (turn on devel, etc.) with help and options, and then call the sequence of commands appropriate for your site with a shell alias that is customized on a per-site basis in an alias file (maybe with a default alias in drushrc.php for your default behavior). We can have a few examples in the drush documentation on some common ones. Simple workflows can be expressed with just a few commands; as things get more complicated, then the alias can be changed to call through to a custom command if desired.

To use commands like sql-sync, we need to replace {{%target}}. To use git and other shell commands, we need to replace {{%root}} and {{%files}}. Not sure what other replacements are necessary, but including everything in path-aliases would be a good start.

:D My progeny will thank you, then.

Perhaps no one will use multiple workflows for the same command name, but different users might pick the workflow that suits them best for commands such as site-pull and site-push. If it is ever useful to chain together multiple commands in a shell alias, then it is useful to support replacements inside shell aliases.

Here is a patch. I tested it with the following shell aliases:

$options['shell-aliases'] = array(
  'test' => '!echo {{@target}} {{%boo}} {{%root}}',
  'site-pull' => '!drush sql-sync {{#peer}} {{@target}} && drush rsync {{#peer}}:%files {{@target}}:%files',
  'site-push' => '!drush rsync {{@target}} {{#peer}} && drush {{#peer}} updatedb',
);

I used these shell aliases with the following site alias:

$aliases['dev'] = array (
  'root' => '/path/to/drupal',
  'uri' => 'mysite.org',
  '#peer' => '@mysite.live',
  'path-aliases' => array (
    '%boo' => '/usr/local/boo',
  ),
);

Why '#peer'? Because site alias elements whose keys begin with '#' never propagate in backend invoke. Why {{%boo}}? Becuase path aliases by convention usually start with %. Why {{@target}}? To differentiate from {{%target}}. That gives us a fair number of possible leading characters in shell alias replacements, but I think they all make sense based on the source of where they came from. {{@target}} is the special one; it could be {{#target}} or {{%target}} if desired; that would give one fewer valid leading characters in the available replacement patterns.

Something of note in drush_core_execute:

-    $args[$x] = drush_escapeshellarg($args[$x]);
+    // escape all args except for command separators.
+    if (!in_array($args[$x], array('&&', '||', ';'))) {
+      $args[$x] = drush_escapeshellarg($args[$x]);
+    }

I omit escaping command separators, &&, || and ;, so that compound commands will actually work. I'm not sure if there might be other special shell sequences that would also need similar treatment.

There are a couple of minor bugfixes in here as well. I will continue with tests, but not sure if I'll have them ready to post tonight. Will put them up soon, though.

Here's a patch with tests that pass. There's one failing test -- site upgrade. I'll look into whether that is related to this issue or not next.

Looks like the failing test is caused by this patch. Will investigate that next.

Doing a pull and rebase seems to have cleared up the failing test. No code changes in this patch other than that; will work on docs and commit.

Whoops, here's a non-empty version of the above patch file.

Committed bbe039f, 71a9ca2 and 63b2a4e to master; includes tests and docs.

I will work on simplifying the documentation for shell alias replacements.

* There are simpler use cases for replacement; I'll find something appropriate to use in the basic documentation. pull-files as an alias for cd %files followed by git pull might be a good candidate.

* I will avoid using the 'peer' nomenclature, and will try to make the examples use concrete terms (@dev, @stage and @prod) instead of the abstract #peer.

* I'll document the push and pull examples in a drush topic, and keep this complexity out of the base examples.