summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGravatar Joey Hess <joeyh@joeyh.name>2015-01-20 12:41:49 -0400
committerGravatar Joey Hess <joeyh@joeyh.name>2015-01-20 12:41:49 -0400
commitdc5500273efc57fdb5382944417c8f028b1b86a9 (patch)
tree3140464ba2a0238aa537e13249420c60c0842ecf
parent401dfc8e9e95ff105cfda7a1d89bc5c5c0aba70c (diff)
add new walkthrough chapter on using special remotes
-rw-r--r--doc/walkthrough.mdwn1
-rw-r--r--doc/walkthrough/using_special_remotes.mdwn53
-rw-r--r--doc/walkthrough/using_ssh_remotes.mdwn10
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