docs/config: mention protocol implications of url.insteadOf

If a URL rewrite switches the protocol to something
nonstandard (like "persistent-https" for "https"), the user
may be bitten by the fact that the default protocol
restrictions are different between the two. Let's drop a
note in insteadOf that points the user in the right
direction.

It would be nice if we could make this work out of the box,
but we can't without knowing the security implications of
the user's rewrite. Only the documentation for a particular
remote helper can advise one way or the other. Since we do
include the persistent-https helper in contrib/ (and since
it was the helper in the real-world case that inspired that
patch), let's also drop a note there.

Suggested-by: Elliott Cable <[email protected]>
Signed-off-by: Jeff King <[email protected]>
Signed-off-by: Junio C Hamano <[email protected]>

Author: peff

Documentation/config.txt

@@ -3208,6 +3208,13 @@ url.<base>.insteadOf::
 	the best alternative for the particular user, even for a
 	never-before-seen repository on the site.  When more than one
 	insteadOf strings match a given URL, the longest match is used.
++
+Note that any protocol restrictions will be applied to the rewritten
+URL. If the rewrite changes the URL to use a custom protocol or remote
+helper, you may need to adjust the `protocol.*.allow` config to permit
+the request.  In particular, protocols you expect to use for submodules
+must be set to `always` rather than the default of `user`. See the
+description of `protocol.allow` above.
 
 url.<base>.pushInsteadOf::
 	Any URL that starts with this value will not be pushed to;

contrib/persistent-https/README

@@ -35,6 +35,16 @@ to use persistent-https:
 [url "persistent-http"]
 	insteadof = http
 
+You may also want to allow the use of the persistent-https helper for
+submodule URLs (since any https URLs pointing to submodules will be
+rewritten, and Git's out-of-the-box defaults forbid submodules from
+using unknown remote helpers):
+
+[protocol "persistent-https"]
+	allow = always
+[protocol "persistent-http"]
+	allow = always
+
 
 #####################################################################
 # BUILDING FROM SOURCE