document bup special remotes

6 files changed, 64 insertions, 6 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 7d0fb3e79..3514002a4 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -402,9 +402,15 @@ Here are all the supported configuration settings.
   to or from this remote. For example, to force ipv6, and limit
   the bandwidth to 100Kbyte/s, set it to "-6 --bwlimit 100"
 
-* `annex.ssh-options`, `annex.rsync-options`
+* `remote.<name>.annex-bup-split-options`
 
-  Default ssh and rsync options to use if a remote does not have
+  Options to pass to bup split when storing content in this remote.
+  For example, to limit the bandwidth to 100Kbye/s, set it to "--bwlimit 100k"
+  (There is no corresponding option for bup join.)
+
+* `annex.ssh-options`, `annex.rsync-options`, `annex.bup-split-options`
+
+  Default ssh, rsync, and bup options to use if a remote does not have
   specific options.
 
 * `annex.diskreserve`
diff --git a/doc/not.mdwn b/doc/not.mdwn
index 1d38b848c..8d5dbd0b5 100644
--- a/doc/not.mdwn
+++ b/doc/not.mdwn
@@ -2,10 +2,8 @@
 
 * git-annex is not a backup system. It may be a useful component of an
   [[archival|use_case/bob]] system, or a way to deliver files to a backup
-  system.
-
-  For a backup system that uses git, take a look at
-  [bup](http://github.com/apenwarr/bup).
+  system. For a backup system that uses git and that git-annex supports
+  storing data in, see [[special_remotes/bup]].
 
 * git-annex is not unison, but if you're finding unison's checksumming
   too slow, or its strict mirroring of everything to both places too
diff --git a/doc/special_remotes.mdwn b/doc/special_remotes.mdwn
index f4d479aa9..a33d3f612 100644
--- a/doc/special_remotes.mdwn
+++ b/doc/special_remotes.mdwn
@@ -7,6 +7,7 @@ types of remotes. These can be used just like any normal remote by git-annex.
 They cannot be used by other git commands though.
 
 * [[Amazon_S3]]
+* [[bup]]
 * [[directory]]
 
 ## Unused content on special remotes
diff --git a/doc/special_remotes/bup.mdwn b/doc/special_remotes/bup.mdwn
new file mode 100644
index 000000000..09eadd008
--- /dev/null
+++ b/doc/special_remotes/bup.mdwn
@@ -0,0 +1,34 @@
+This special remote type stores file contents in a 
+[bup](http://github.com/apenwarr/bup) repository. By using git-annex
+in the front-end, and bup as a remote, you get an easy git-style
+interface to large files, and easy backups of the file contents using git.
+
+See [[walkthrough/using_bup]] for usage examples.
+
+## configuration
+
+These parameters can be passed to `git annex initremote` to configure bup:
+
+* `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.
+
+* `remote` - Required. This is passed to `bup` as the `--remote`
+  to use to store data. `bup init` will be run to create the
+  repository. Example: "remote=example.com:/big/mybup"
+
+Options to pass to `bup split` when sending content to bup can also
+be specified, by using `git config annex.bup-split-options`. This
+can be used to, for example, limit its bandwidth.
+
+## data security
+
+When encryption=none, there is **no** protection against your data being read
+by anyone who can access the bup remote. However, bup does transfer data
+using ssh, and if you trust the security of the remote, that's fine.
+
+** Encryption is not yet supported. **
+
+See [[design/encryption]].
diff --git a/doc/walkthrough.mdwn b/doc/walkthrough.mdwn
index 53f0be6bb..c64880749 100644
--- a/doc/walkthrough.mdwn
+++ b/doc/walkthrough.mdwn
@@ -15,6 +15,7 @@ A walkthrough of the basic features of git-annex.
 	using_ssh_remotes
 	moving_file_content_between_repositories
 	using_Amazon_S3
+	using_bup
 	using_the_URL_backend
 	using_the_SHA1_backend
 	migrating_data_to_a_new_backend
diff --git a/doc/walkthrough/using_bup.mdwn b/doc/walkthrough/using_bup.mdwn
new file mode 100644
index 000000000..1a506c281
--- /dev/null
+++ b/doc/walkthrough/using_bup.mdwn
@@ -0,0 +1,18 @@
+Another [[special_remote|special_remotes]] that git-annex can use is
+a [[special_remotes/bup]] repository. Bup stores large file contents
+in a git repository of its own, with deduplication. Combined with
+git-annex, you can have git on both the frontend and the backend.
+
+Here's how to create a bup remote, and describe it.
+
+	# git annex initremote mybup type=bup encryption=none remote=example.com/big/mybup
+	initremote bup (init) ok
+	# git annex describe mybup "my bup repository at example.com"
+	describe mybup ok
+
+Now the remote can be used like any other remote.
+
+	# git annex move my_cool_big_file --to mybup
+	move my_cool_big_file (to mybup...) ok
+
+See [[special_remotes/bup]] for details.