rsync special remote

Fully tested and working, including resuming and encryption. (Though not
resuming when sending *with* encryption; gpg doesn't produce identical
output each time.)

Uses same layout as the directory special remote and the .git/annex/objects/
directory.

4 files changed, 44 insertions, 4 deletions

diff --git a/doc/forum/wishlist:_special_remote_for_sftp_or_rsync.mdwn b/doc/forum/wishlist:_special_remote_for_sftp_or_rsync.mdwn
index becfe23c7..9807bf91e 100644
--- a/doc/forum/wishlist:_special_remote_for_sftp_or_rsync.mdwn
+++ b/doc/forum/wishlist:_special_remote_for_sftp_or_rsync.mdwn
@@ -1,5 +1,21 @@
-i think it would be useful to have a fourth kind of [[special remote]]s that connects to a dumb storage using sftp or rsync. this can be emulated by using sshfs, but that means lots of round-trips through the system and is limited to platforms where sshfs is available.
+i think it would be useful to have a fourth kind of [[special remote]]s
+that connects to a dumb storage using sftp or rsync. this can be emulated
+by using sshfs, but that means lots of round-trips through the system and
+is limited to platforms where sshfs is available.
 
-typical use cases are backups to storate shared between a group of people where each user only has limited access (sftp or rsync), when using [[bup]] is not an option.
+typical use cases are backups to storate shared between a group of people
+where each user only has limited access (sftp or rsync), when using [[bup]]
+is not an option.
 
-an alternative to implementing yet another special remote would be to have some kind of plugin system by which external programs can provide an interface to key-value stores (i'd implement the sftp backend myself, but haven't learned haskell yet).
+an alternative to implementing yet another special remote would be to have
+some kind of plugin system by which external programs can provide an
+interface to key-value stores (i'd implement the sftp backend myself, but
+haven't learned haskell yet).
+
+> Ask and ye [[shall receive|special_remotes/rsync]].
+> 
+> Sometimes I almost think that a generic configurable special remote that
+> just uses configured shell commands would be useful.. But there's really
+> no comparison with sitting down and writing code tuned to work with
+> a given transport like rsync, when it comes to reliability and taking
+> advantage of its abilities (like resuming). --[[Joey]]
diff --git a/doc/special_remotes.mdwn b/doc/special_remotes.mdwn
index a33d3f612..210f995d2 100644
--- a/doc/special_remotes.mdwn
+++ b/doc/special_remotes.mdwn
@@ -9,6 +9,7 @@ They cannot be used by other git commands though.
 * [[Amazon_S3]]
 * [[bup]]
 * [[directory]]
+* [[rsync]]
 
 ## Unused content on special remotes
 
diff --git a/doc/special_remotes/directory.mdwn b/doc/special_remotes/directory.mdwn
index 8006c44fc..9e4bfa33b 100644
--- a/doc/special_remotes/directory.mdwn
+++ b/doc/special_remotes/directory.mdwn
@@ -7,4 +7,4 @@ the drive's mountpoint as a directory remote.
 
 Setup example:
 
-	# git annex initremote usbdrive directory=/media/usbdrive/ encryption=none
+	# git annex initremote usbdrive type=directory directory=/media/usbdrive/ encryption=none
diff --git a/doc/special_remotes/rsync.mdwn b/doc/special_remotes/rsync.mdwn
new file mode 100644
index 000000000..593644291
--- /dev/null
+++ b/doc/special_remotes/rsync.mdwn
@@ -0,0 +1,23 @@
+This special remote type rsyncs file contents to somewhere else.
+
+Setup example:
+
+	# git annex initremote myrsync type=rsync rsyncurl=rsync://rsync.example.com/myrsync encryption=joey@kitenet.net
+
+## configuration
+
+These parameters can be passed to `git annex initremote` to configure rsync:
+
+* `encryption` - Required. Either "none" to disable encryption of content
+  stored in rsync, 
+  or a value that can be looked up (using gpg -k) to find a gpg encryption
+  key that will be given access to the remote. Note that additional gpg
+  keys can be given access to a remote by rerunning initremote with
+  the new key id. See [[encryption]].
+
+* `rsyncurl` - Required. This is the url or `hostname:/directory` to 
+  pass to rsync to tell it where to store content.
+
+The `annex-rsync-options` git configuration setting can be used to pass
+parameters to rsync. Note that it is **not safe** to put "--delete"
+in `annex-rsync-options` when using rsync special remotes.