documentation for hook special remotes

Releasing before I have quite finished the code. Got a little caught
up in Anathem references. Time for a walk and then a tiny bit more coding
and possibly testing.

1 files changed, 65 insertions, 0 deletions

diff --git a/doc/special_remotes/hook.mdwn b/doc/special_remotes/hook.mdwn
new file mode 100644
index 000000000..521b44027
--- /dev/null
+++ b/doc/special_remotes/hook.mdwn
@@ -0,0 +1,65 @@
+This special remote type runs hooks that you configure to store content.
+
+It's not recommended to use this remote type when another like [[rsync]]
+or [[directory]] will do. If your hooks are not carefully written, data
+could be lost.
+
+## example
+
+Here's a simple example that stores content on clay tablets. If you
+implement this example in the real world, I'd appreciate a tour
+next Apert! :) --[[Joey]]
+
+	# git config annex.cuneiform-store-hook 'tocuneiform < $ANNEX_FILE | tablet-writer --implement=stylus --title=$ANNEX_KEY | tablet-proofreader | librarian --shelve --floor=$ANNEX_HASH_1 --shelf=$ANNEX_HASH_2'
+	# git config annex.cuneiform-retrieve-hook 'librarian --get --floor=$ANNEX_HASH_1 --shelf=$ANNEX_HASH_2 --title=$ANNEX_KEY | tablet-reader --implement=coffee --implement=glasses --force-monastic-dedication | fromcuneiform > $ANNEX_FILE'
+	# git config annex.cuneiform-remove-hook 'goon --hit-with-hammer --floor=$ANNEX_HASH_1 --shelf=$ANNEX_HASH_2 --title=$ANNEX_KEY'
+	# git config annex.cuneiform-checkpresent-hook 'librarian --find --force-distrust-catalog --floor=$ANNEX_HASH_1 --shelf=$ANNEX_HASH_2 --title=$ANNEX_KEY --shout-title'
+	# git annex initremote special type=hook hooktype=cuneiform encryption=none
+
+Can you spot the potential data loss bugs in the above simple example?
+(Hint: What happens when the `tablet-proofreader` exits nonzero?)
+
+## configuration
+
+These parameters can be passed to `git annex initremote`:
+
+* `encryption` - Required. Either "none" to disable encryption of content,
+  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]].
+
+* `hooktype` - Required. This specifies a collection of hooks to use for
+  this remote.
+
+## hooks
+
+Each type of hook remote is specified by a collection of hook commands.
+Each hook command is run as a shell command line, and should return nonzero
+on failure, and zero on success.
+
+These environment variables are used to communicate with the hook commands:
+
+* `ANNEX_KEY` - name of a key to store, retrieve, remove, or check.
+* `ANNEX_FILE` - a file containing the key's content
+* `ANNEX_HASH_1` - short stable value, based on the key, can be used for hashing
+* `ANNEX_HASH_2` - another hash value, can be used for a second level of hashing
+
+The setting to use in git config for the hook commands are as follows:
+
+* `annex.$hooktype-store-hook` - Command run to store a key in the special remote.
+  `ANNEX_FILE` contains the content to be stored.
+
+* `annex.$hooktype-retrieve-hook` - Command run to retrieve a key from the special remote.
+  `ANNEX_FILE` is a file that the retrieved content should be written to.
+  The file may already exist with a partial
+  copy of the content (or possibly just garbage), to allow for resuming
+  of partial transfers.
+
+* `annex.$hooktype-remove-hook` - Command to remove a key from the special remote.
+
+* `annex.$hooktype-checkpresent-hook` - Command to check if a key is present
+  in the special remote. Should output the key name to stdout, on its own line,
+  if and only if the key has been actively verified to be present in the
+  special remote (caching presence information is a very bad idea);
+  all other output to stdout will be ignored.