diff --git a/doc/bugs/annex-rsync-options_shell-split_carelessly.mdwn b/doc/bugs/annex-rsync-options_shell-split_carelessly.mdwn
new file mode 100644
index 0000000000..c8eeb7160d
--- /dev/null
+++ b/doc/bugs/annex-rsync-options_shell-split_carelessly.mdwn
@@ -0,0 +1,16 @@
+with rsync, it is sometimes the case that one needs to specify ssh options -- typical examples from the rsync man page are `rsync  -e 'ssh -p 2234'`. as git-annex does the shell splitting of the arguments in `annex-rsync-options` (see [[special remotes/rsync]]) itself by looking for whitespace, these options can't be passed directly. (`annex-rsync-options = -e 'ssh -p 2234'` gets split to `["rsync", "-e", "'ssh", "-p", "2234'"]` instead of `["rsync", "-e", "ssh -p 2234"]`).
+
+git-annex should respect shell splitting rules when looking at annex-rsync-options. (i suppose there is a haskell library or module for that; in python, we have the `shlex` module for that).
+
+## workaround
+
+put this in .git/ssh and mark it as executable:
+
+    #!/bin/sh
+    exec ssh -p 2234 $@
+
+put this in your git annex config in the particular remote's section:
+
+    annex-rsync-options = -e /local/path/to/your/repo/.git/ssh
+
+(typical bug report information: observed with git-annex 3.20121127 on debian)
diff --git a/doc/bugs/annex-rsync-options_shell-split_carelessly/comment_1_2636e0d224317f2e6db94658d8a094c4._comment b/doc/bugs/annex-rsync-options_shell-split_carelessly/comment_1_2636e0d224317f2e6db94658d8a094c4._comment
new file mode 100644
index 0000000000..42b92ce281
--- /dev/null
+++ b/doc/bugs/annex-rsync-options_shell-split_carelessly/comment_1_2636e0d224317f2e6db94658d8a094c4._comment
@@ -0,0 +1,23 @@
+[[!comment format=mdwn
+ username="http://joeyh.name/"
+ ip="4.153.8.117"
+ subject="comment 1"
+ date="2012-12-13T17:03:08Z"
+ content="""
+Due to the way git-annex runs rsync, which involves a specific -e parameter it constructs that, you cannot pass -e in annex-rsync-options anyway; or if you do you'll bypass use of git-annex-shell, which is not desirable. I have not checked which, but would not recommend use of it.
+
+There is no need for ugly workarounds. Just use ~/.ssh/config to configure the hostname to use the nonstandard port it needs. For example:
+
+<pre>
+Host example.com
+Port 2234
+</pre>
+
+Or, to make a separate example.com-2234 host that can be used to use the nonstandard port:
+
+<pre>
+Host example.com-2234
+Hostname example.com
+Port 2234
+</pre>
+"""]]