Site alias documentation

Thanks for the review. It is enlightening for me to see some of the details in the corners.
The walkthrough is a little bit stream-of-consciousness style, and is written as a first-time user taking one of many possible paths, so there are probably plenty of assumptions made.

RE sitename/bashrc.php
I understood the reasoning for that not triggering, and did try to test it first to see if my preferred approach would work first. I'd still like a way for a site to just define information locally about its default preferred peer, but it wasn't too much of an issue. I've softened that comment and demoted it to an aside.

RE authentication
Setting up ssh keys is now second nature to me, but I'd assumed other folk may get prompted for their pass a few times. I've updated the comment from 'tip' to 'requirement' to reflect this.
This is a little frustrating to know, as I have had some cases where due to limited permissions on the server, I could get shell but not ssh keys working :-/.
I didn't want to get into documenting that too much there, as this practice is a tip that should be covered elsewhere.
FWIW, my less-cute personal version of 'pushkey' is a one-liner that looks like:

RE site folder aliases.
I know exactly what you are saying. In the real world, I do in fact do it a little differently. For a while now, I've been creating:

RE !drush-script
I just had to note that to myself at the time because the example.drushrc.php internal documentation was not quite obvious.
'!drush' => '/drush/path/drush',
... I'll rewrite my comment, as it is indeed redundant if I actually read the comments nearby in the file :-)

RE drush not entirely required.
Noted. Very Cool, did not know that, and it is going to be simpler for me, I prefer to have a copy of remote details stored locally. I added an update about skipping that step.
I got the impression that there was an intention to make the remote drush instance do lots more work, like an RPC endpoint (and was a bit sceptical about that approach) but if it remains working as a local set of instructions sent to a remote machine, I'm very happy with that.
... I guess I can remove one of the cogs from my illustration :-B. Damn. I made it a cog just so I could plug them together!

RE !dump.
commented on-issue there.

RE caches.
In my experience, it makes more sense to flush caches and watchdog immediately before taking a dump, because that makes the SQL several times smaller. I've noted the 'cc' action (which I didn't know of) at the bottom of my write-up anyway.
Would it be good practice for sql sync to do that itself? does it already?

I may still get around to patching in the missing db prefix support for the project one day... I'm just stepping through an automated backup/testsuite setup so hitting (and documenting) things as I come across them. I had 20 multisites in one (dev/demo) DB, and it slowed the db export down with a lot of redundancy. Thought I'd get up to speed with drush sync as a replacement for my own scripts (so far it's pretty much the same as my hand-rolled versions - which is a good sign).

Glad I didn't make too many gross misunderstandings in my write-up there! I find making notes to be quite theraputic, especially when the system i'm documenting is more clever than me!

(PS, did my placing a purely decorative image in the HTML lock it from editing for you?)

Hm. Cache clearing is a fuzzy one. Different needs in different cases. In the past I've tried various methods, but what you are currently doing with the 'no-data' options is the best I can imagine at the moment.

I'd not yet encountered the remote invocation syntax, but knew it was in the pipeline. Good to know that drush my.drupalsite.remote cc is the magic word.

I guess there are some issues with multi-shared table prefixes, but I've not had to use them yet. I can start with simple per-site prefixes and just freak out if there is an array ... for now. It'll only happen as I find a need for it in real sites. If I have to imagine all possible futures, even ones that don't apply to me, nothing will happen.
Currently however the all-my-neighbours-tables behaviour is undesirable, so I'll want to detect and fix that. I'm setting up a bunch of rapid-development small sites that have most things in common, including the DB itself, as a host won't let me CREATE DATABASE on the fly.
I've also developed code that (so far seems to) handle prefix-rewriting on the fly, including prefixed-to-not and back (just a few regexps through sed) so I'd like to plug that in. I've found it useful/neccessary in some migrations. I work with many different companies that have different conventions about setting stuff up, and try to make my local dev mirrors as consistent+agnostic as possible, so I've seen plenty of variety.
I will not speculate about why someone would have entirely different structured schemas on two sites they intended to keep in synch!

RE edit locking
Yeah, I was afraid of that. In order to insert an image on d.o, the input format is slightly advanced, for the 'documentation' role. (I'm a d.o doc maintainer). However, this has the side effect of not letting other non-maintainers touch my code. I'll have to remove my pretty picture if I want to open up that page to public edits :-/

Anything left to do here? I added 'site maintainer' role to greg's account so he can tweak the documentation when inspiration enters the mind.

I added links to dman's doc from README.txt and includes/sitealias.inc

Seems like we are done here. If not, please reopen.

There is a minor issue in example.aliases.drushrc.php with a part of an old sentence that was not completely deleted:

 * Files stored in these locations can be used to create aliases
 * to local and remote Drupal installations.  These aliases can beTo create aliases to remote Drupal installations, add entries
 * used in place of a site specification on the command line, and

This is great. how do i install this command on osx? i downloaded the file and saved as pushkey.sh in /bin then chmod +X. but still no dice.

Works fine on osx for me
If you saved it with the .sh extension, that's what you'll have to type

i just tried this script on one of my clean CENTOS images and it spit this out

/bin/sh: /root/.ssh/AContent_id_rsa.pub: No such file or directory

?

For future pushkey-type support, I recommend looking at ssh-copy-id http://linux.die.net/man/1/ssh-copy-id which now comes with the ssh package (AFAIK) and just does this common task for you.