6 files changed, 61 insertions, 37 deletions
diff --git a/doc/special_remotes/S3.mdwn b/doc/special_remotes/S3.mdwn
index 79a8e584a..5a7ecc25b 100644
--- a/doc/special_remotes/S3.mdwn
+++ b/doc/special_remotes/S3.mdwn
@@ -8,21 +8,29 @@ See [[tips/using_Amazon_S3]] and
 
 The standard environment variables `AWS_ACCESS_KEY_ID` and 
 `AWS_SECRET_ACCESS_KEY` are used to supply login credentials
-for Amazon. When encryption is enabled, they are stored in encrypted form
-by `git annex initremote`. Without encryption, they are stored in a
-file only you can read inside the local git repository. So you do not
-need to keep the environment variables set after the initial
-initalization of the remote.
+for Amazon. You need to set these only when running
+`git annex initremote`, as they will be cached in a file only you
+can read inside the local git repository.
 
 A number of parameters can be passed to `git annex initremote` to configure
 the S3 remote.
 
-* `encryption` - Required. Either "none" to disable encryption
-  (not recommended),
+* `encryption` - Required. Either "none" to disable encryption (not recommended),
   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]].
+  key that will be given access to the remote, or "shared" which allows
+  every clone of the repository to access the encrypted data (use with caution).
+
+  Note that additional gpg keys can be given access to a remote by
+  rerunning initremote with the new key id. See [[encryption]].
+
+* `embedcreds` - Optional. Set to "yes" embed the login credentials inside
+  the git repository, which allows other clones to also access them. This is
+  the default when gpg encryption is enabled; the credentials are stored
+  encrypted and only those with the repository's keys can access them.
+
+  It is not the default when using shared encryption, or no encryption.
+  Think carefully about who can access your repository before using
+  embedcreds without gpg encryption.
 
 * `datacenter` - Defaults to "US". Other values include "EU",
   "us-west-1", and "ap-southeast-1".
diff --git a/doc/special_remotes/bup.mdwn b/doc/special_remotes/bup.mdwn
index e59ff240d..519b5607f 100644
--- a/doc/special_remotes/bup.mdwn
+++ b/doc/special_remotes/bup.mdwn
@@ -22,9 +22,11 @@ These parameters can be passed to `git annex initremote` to configure bup:
 * `encryption` - Required. Either "none" to disable encryption of content
   stored in bup (ssh will still be used to transport it securely),
   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]].
+  key that will be given access to the remote, or "shared" which allows
+  every clone of the repository to access the encrypted data (use with caution).
+
+  Note that additional gpg keys can be given access to a remote by
+  rerunning initremote with the new key id. See [[encryption]].
 
 * `buprepo` - Required. This is passed to `bup` as the `--remote`
   to use to store data. To create the repository,`bup init` will be run.
diff --git a/doc/special_remotes/directory.mdwn b/doc/special_remotes/directory.mdwn
index 7194e0d8e..7fdfdfca0 100644
--- a/doc/special_remotes/directory.mdwn
+++ b/doc/special_remotes/directory.mdwn
@@ -10,12 +10,14 @@ the drive's mountpoint as a directory remote.
 These parameters can be passed to `git annex initremote` to configure the
 remote:
 
-* `encryption` - Required. Either "none" to disable encryption of content
-  stored in the directory,
+* `encryption` - Required. Either "none" to disable encryption,
   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]].
+  key that will be given access to the remote, or "shared" which allows
+  every clone of the repository to decrypt the encrypted data.
+
+  Note that additional gpg keys can be given access to a remote by
+  rerunning initremote with the new key id. See [[encryption]].
+
 * `chunksize` - Avoid storing files larger than the specified size in the
   directory. For use on directories on mount points that have file size
   limitations. The default is to never chunk files.  
diff --git a/doc/special_remotes/hook.mdwn b/doc/special_remotes/hook.mdwn
index 9a7dbf7a1..6867edb8f 100644
--- a/doc/special_remotes/hook.mdwn
+++ b/doc/special_remotes/hook.mdwn
@@ -25,11 +25,13 @@ Can you spot the potential data loss bugs in the above simple example?
 
 These parameters can be passed to `git annex initremote`:
 
-* `encryption` - Required. Either "none" to disable encryption of content,
+* `encryption` - Required. Either "none" to disable encryption,
   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]].
+  key that will be given access to the remote, or "shared" which allows
+  every clone of the repository to access the encrypted data.
+
+  Note that additional gpg keys can be given access to a remote by
+  rerunning initremote with the new key id. See [[encryption]].
 
 * `hooktype` - Required. This specifies a collection of hooks to use for
   this remote.
diff --git a/doc/special_remotes/rsync.mdwn b/doc/special_remotes/rsync.mdwn
index 273469258..f98c80a83 100644
--- a/doc/special_remotes/rsync.mdwn
+++ b/doc/special_remotes/rsync.mdwn
@@ -15,11 +15,13 @@ Or for using rsync over SSH
 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]].
+  stored on the remote rsync server,
+  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, or "shared" which allows
+  every clone of the repository to decrypt the encrypted data.
+
+  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.
diff --git a/doc/special_remotes/webdav.mdwn b/doc/special_remotes/webdav.mdwn
index 8421dd5f4..570b6f949 100644
--- a/doc/special_remotes/webdav.mdwn
+++ b/doc/special_remotes/webdav.mdwn
@@ -3,21 +3,29 @@ This special remote type stores file contents in a WebDAV server.
 ## configuration
 
 The environment variables `WEBDAV_USERNAME` and `WEBDAV_PASSWORD` are used
-to supply login credentials. When encryption is enabled, they are stored in
-encrypted form by `git annex initremote`. Without encryption, they are
-stored in a file only you can read inside the local git repository. So you
-do not need to keep the environment variables set after the initial
-initalization of the remote.
+to supply login credentials. You need to set these only when running
+`git annex initremote`, as they will be cached in a file only you 
+can read inside the local git repository.
 
 A number of parameters can be passed to `git annex initremote` to configure
 the webdav remote.
 
-* `encryption` - Required. Either "none" to disable encryption
-  (not recommended),
+* `encryption` - Required. Either "none" to disable encryption (not recommended),
   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]].
+  key that will be given access to the remote, or "shared" which allows
+  every clone of the repository to access the encrypted data (use with caution).
+
+  Note that additional gpg keys can be given access to a remote by
+  rerunning initremote with the new key id. See [[encryption]].
+
+* `embedcreds` - Optional. Set to "yes" embed the login credentials inside
+  the git repository, which allows other clones to also access them. This is
+  the default when gpg encryption is enabled; the credentials are stored
+  encrypted and only those with the repository's keys can access them.
+
+  It is not the default when using shared encryption, or no encryption.
+  Think carefully about who can access your repository before using
+  embedcreds without gpg encryption.
 
 * `url` - Required. The URL to the WebDAV directory where files will be
   stored. This can be a subdirectory of a larger WebDAV repository, and will