add new walkthrough chapter on using special remotes

3 files changed, 59 insertions, 5 deletions

diff --git a/doc/walkthrough.mdwn b/doc/walkthrough.mdwn
index 94c31e477..94889864a 100644
--- a/doc/walkthrough.mdwn
+++ b/doc/walkthrough.mdwn
@@ -14,6 +14,7 @@ A walkthrough of the basic features of git-annex.
 	walkthrough/removing_files:_When_things_go_wrong
 	walkthrough/modifying_annexed_files
 	walkthrough/using_ssh_remotes
+	walkthrough/using_special_remotes
 	walkthrough/moving_file_content_between_repositories
 	walkthrough/quiet_please:_When_git-annex_seems_to_skip_files
 	walkthrough/using_tags_and_branches
diff --git a/doc/walkthrough/using_special_remotes.mdwn b/doc/walkthrough/using_special_remotes.mdwn
new file mode 100644
index 000000000..427baadd9
--- /dev/null
+++ b/doc/walkthrough/using_special_remotes.mdwn
@@ -0,0 +1,53 @@
+We've seen above that git-annex can be used to store files in
+regular git remotes, accessed either via ssh, or on a removable drive. But
+git-annex can also store files in Amazon S3, Glacier, on a rsync server, in
+WebDAV, or even pull files down from the web and bittorrent.
+This and much more is made possible by [[special_remotes]].
+
+These are not normal git repositories; indeed the git repository is not
+stored on a special remote. But git-annex can store the contents of files
+in special remotes, and operate on them much as it would on any other
+remote. Bonus: Files stored on special remotes can easily be
+[[encrypted|encryption]]!
+
+All you need to get started using a special remote is to initialize it.
+This is done using the `git annex initremote` command, which needs to be
+passed different parameters depending on the type of special remote.
+
+Some special remotes also need things like passwords to be set in
+environment variables. Don't worry -- it will prompt if you leave anything off.
+So feel free to make any kind of special remote instead of the S3 remote
+used in this example.
+
+	# export AWS_ACCESS_KEY_ID="somethingotherthanthis"
+	# export AWS_SECRET_ACCESS_KEY="s3kr1t"
+	# git annex initremote mys3 type=S3 chunk=1MiB encryption=shared
+	initremote mys3 (shared encryption) (checking bucket) (creating bucket in US) ok
+
+Now you can store files on the newly initialized special remote.
+
+	# git annex copy my_cool_big_file --to mys3
+	copy my_cool_big_file (to mys3...) ok
+
+Once you've initialized a special remote in one repository, you can enable
+use of the same special remote in other clones of the repository.
+If the mys3 remote above was initialized on your laptop, you'll also want
+to enable it on your desktop.
+
+To do so, first get git-annex in sync (so it knows about
+the special remote that was added in the other repository), and then
+use `git annex enableremote`.
+
+	desktop# git annex sync
+	desktop# export AWS_ACCESS_KEY_ID="somethingotherthanthis"
+	desktop# export AWS_SECRET_ACCESS_KEY="s3kr1t"
+	desktop# git annex enableremote mys3
+	enableremote mys3 (checking bucket) ok
+
+And now you can download files from the special remote:
+
+	desktop# git annex get my_cool_big_file --from mys3
+	get my_cool_big_file (from mys3...) ok
+
+This has only scratched the surface of what can be done with
+[[special_remotes]].
diff --git a/doc/walkthrough/using_ssh_remotes.mdwn b/doc/walkthrough/using_ssh_remotes.mdwn
index 1dc8fa55b..ee8b629fa 100644
--- a/doc/walkthrough/using_ssh_remotes.mdwn
+++ b/doc/walkthrough/using_ssh_remotes.mdwn
@@ -5,13 +5,13 @@ that is truly remote, a host accessed by ssh.
 Say you have a desktop on the same network as your laptop and want
 to clone the laptop's annex to it:
 
-	# git clone ssh://mylaptop/home/me/annex ~/annex
-	# cd ~/annex
-	# git annex init "my desktop"
+	desktop# git clone ssh://mylaptop/home/me/annex ~/annex
+	desktop# cd ~/annex
+	desktop# git annex init "my desktop"
 
 Now you can get files and they will be transferred (using `rsync` via `ssh`):
 
-	# git annex get my_cool_big_file
+	desktop# git annex get my_cool_big_file
 	get my_cool_big_file (getting UUID for origin...) (from origin...)
 	SHA256-s86050597--6ae2688bc533437766a48aa19f2c06be14d1bab9c70b468af445d4f07b65f41e  100% 2159     2.1KB/s   00:00
 	ok
@@ -19,7 +19,7 @@ Now you can get files and they will be transferred (using `rsync` via `ssh`):
 When you drop files, git-annex will ssh over to the remote and make
 sure the file's content is still there before removing it locally:
 
-	# git annex drop my_cool_big_file
+	desktop# git annex drop my_cool_big_file
 	drop my_cool_big_file (checking origin..) ok
 
 Note that normally git-annex prefers to use non-ssh remotes, like