summaryrefslogtreecommitdiff
path: root/doc/special_remotes
diff options
context:
space:
mode:
authorGravatar Joey Hess <joey@kitenet.net>2011-04-28 15:26:21 -0400
committerGravatar Joey Hess <joey@kitenet.net>2011-04-28 15:26:21 -0400
commit07576f2a2c84a54dc3b0e2aa6050e747f29c3a43 (patch)
tree455e71ed355cb73c8e8e6caa2570c95036bc124d /doc/special_remotes
parentd7b330b33bcfa57164dad05b0fc9990ad4a35275 (diff)
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.
Diffstat (limited to 'doc/special_remotes')
-rw-r--r--doc/special_remotes/hook.mdwn65
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.