docs: clarify remote restrictions for git-upload-archive
Commits ee27ca4 and 0f544ee introduced rules by which
git-upload-archive would restrict clients from accessing
unreachable objects. However, we never documented those
rules anywhere, nor their reason for being. Let's do so now.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index b97aaab..cfa1e4e 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -65,7 +65,10 @@
--remote=<repo>::
Instead of making a tar archive from the local repository,
- retrieve a tar archive from a remote repository.
+ retrieve a tar archive from a remote repository. Note that the
+ remote repository may place restrictions on which sha1
+ expressions may be allowed in `<tree-ish>`. See
+ linkgit:git-upload-archive[1] for details.
--exec=<git-upload-archive>::
Used with --remote to specify the path to the
diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt
index d09bbb5..8ae65d8 100644
--- a/Documentation/git-upload-archive.txt
+++ b/Documentation/git-upload-archive.txt
@@ -20,6 +20,32 @@
for the protocol is on the 'git archive' side, and the program pair
is meant to be used to get an archive from a remote repository.
+SECURITY
+--------
+
+In order to protect the privacy of objects that have been removed from
+history but may not yet have been pruned, `git-upload-archive` avoids
+serving archives for commits and trees that are not reachable from the
+repository's refs. However, because calculating object reachability is
+computationally expensive, `git-upload-archive` implements a stricter
+but easier-to-check set of rules:
+
+ 1. Clients may request a commit or tree that is pointed to directly by
+ a ref. E.g., `git archive --remote=origin v1.0`.
+
+ 2. Clients may request a sub-tree within a commit or tree using the
+ `ref:path` syntax. E.g., `git archive --remote=origin v1.0:Documentation`.
+
+ 3. Clients may _not_ use other sha1 expressions, even if the end
+ result is reachable. E.g., neither a relative commit like `master^`
+ nor a literal sha1 like `abcd1234` is allowed, even if the result
+ is reachable from the refs.
+
+Note that rule 3 disallows many cases that do not have any privacy
+implications. These rules are subject to change in future versions of
+git, and the server accessed by `git archive --remote` may or may not
+follow these exact rules.
+
OPTIONS
-------
<directory>::
