From a6a03ca5860de4a1578f8787b4243fb035415d97 Mon Sep 17 00:00:00 2001
From: Joey Hess <joeyh@joeyh.name>
Date: Tue, 23 Jul 2024 08:42:33 -0400
Subject: [PATCH] annex+http urls

---
 doc/design/p2p_protocol_over_http.mdwn |  5 +++++
 doc/git-annex-p2phttp.mdwn             | 17 +++++++++++++----
 doc/git-annex.mdwn                     |  7 ++++++-
 3 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/doc/design/p2p_protocol_over_http.mdwn b/doc/design/p2p_protocol_over_http.mdwn
index 228f6d734c..af3c3702ca 100644
--- 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 50653437d9..dc2a02f236 100644
--- 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 1bb178dc00..6700b5c852 100644
--- 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.