annex+http urls

diff --git a/doc/design/p2p_protocol_over_http.mdwn b/doc/design/p2p_protocol_over_http.mdwn
index 228f6d734c01986f1af2000407467a05e6b3fd7b..af3c3702ca54fc821b5e39505217e16129a080fe 100644 (file)
--- a/doc/design/p2p_protocol_over_http.mdwn
+++ b/doc/design/p2p_protocol_over_http.mdwn
@@ -7,6 +7,11 @@ connection (mostly). This is a translation of that protocol to HTTP.
 
 [[git-annex-p2phttp]] serves this protocol.
 
+To indicate that an url uses this protocol, use 
+`annex+http` or `annex+https` as the url scheme. Such an url uses
+port 9417 by default, although another port can be specified. For example,
+`annex+http://example.com/` or `annex+http://example.com:80/`
+
 ## base64 encoding of keys, uuids, and filenames
 
 A git-annex key can contain text in any encoding. So can a filename,

diff --git a/doc/git-annex-p2phttp.mdwn b/doc/git-annex-p2phttp.mdwn
index 50653437d9a89f37a29ad3a06327f4757313bc80..dc2a02f236fbe0c58a1c4ea86dcf979977818cbd 100644 (file)
--- a/doc/git-annex-p2phttp.mdwn
+++ b/doc/git-annex-p2phttp.mdwn
@@ -1,6 +1,6 @@
 # NAME
 
-git-annex-p2phttp - HTTP server for git-annex P2P protocol
+git-annex-p2phttp - HTTP server for the git-annex API
 
 # SYNOPSIS
 
@@ -8,15 +8,23 @@ git-annex p2phttp
 
 # DESCRIPTION
 
-This allows a git-annex repository to be accessed over HTTP.
+This is a HTTP server for the git-annex API.
 It is the git-annex equivilant of git-http-backend(1), for serving
 a repository over HTTP with write access for authenticated users.
 
+This does not serve the git repository over HTTP, only the git-annex
+API.
+
+Typically a remote will have `remote.name.url` set to a http url
+as usual, and `remote.name.annexUrl` set to an annex+http url such as
+`annex+http://example.com/`. The annex+http url is served by this
+server, and uses port 9417 by default.
+
 As well as serving the git-annex HTTP API, this server provides a
 convenient way to download the content of any key, by using the path
 "/git-annex/$uuid/$key". For example:
 
-       $ curl http://localhost:9417/git-annex/f11773f0-11e1-45b2-9805-06db16768efe/key/SHA256E-s6--5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
+       $ curl http://example.com:9417/git-annex/f11773f0-11e1-45b2-9805-06db16768efe/key/SHA256E-s6--5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
        hello
 
 # OPTIONS
@@ -33,7 +41,8 @@ convenient way to download the content of any key, by using the path
 
 * `--port=N`
 
-  Port to listen on. Default is port 9417.
+  Port to listen on. The default is port 9417, which is the default
+  port used for an annex+http or annex+https url.
 
   It is not recommended to run this command as root in order to
   use a low port like port 80. It will not drop permissions when run as

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 1bb178dc00b50888af0ad19c49691a83dc2afe9c..6700b5c8528ddb5ae4a3e22d4e55020f6a195ce1 100644 (file)
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -1537,9 +1537,14 @@ Remotes are configured using these settings in `.git/config`.
 * `remote.<name>.annexUrl`
 
   Can be used to specify a different url than the regular `remote.<name>.url`
-  for git-annex to use when talking with the remote. Similar to the `pushUrl`
+  for git-annex to use for accessing the remote. Similar to the `pushUrl`
   used by git-push.
 
+  When this is set to an annex+http or annex+https url, that url is used
+  for git-annex operations only, and the `remote.<name>.url` is used for
+  git operations. This allows using [[git-annex-p2phttp]] to serve a
+  git-annex repository over http.
+
 * `remote.<name>.annex-uuid`
 
   git-annex caches UUIDs of remote repositories here.