docs: clarify the interaction of transfer.hideRefs and namespaces
Expand the section about namespaces in the documentation of `transfer.hideRefs` to point out the subtle differences between `upload-pack` and `receive-pack`. ffcfb68176 (upload-pack.c: treat want-ref relative to namespace, 2021-07-30) taught `upload-pack` to reject `want-ref`s for hidden refs, which is now mentioned. It is clarified that at no point the name of a hidden ref is revealed, but the object id it points to may. Signed-off-by: Kim Altintop <kim@eagain.st> Reviewed-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Kim Altintop committed
Aug 13, 2021 at 06:23 UTC
53a66ec37cfd8fc9f9357f201ae16ae3e8795606
1 file changed
+9
-5
Documentation/config/transfer.txt
+9
-5
@@ -52,13 +52,17 @@ If you have multiple hideRefs values, later entries override earlier ones
52
(and entries in more-specific config files override less-specific ones).
53
+
54
If a namespace is in use, the namespace prefix is stripped from each
55
-reference before it is matched against `transfer.hiderefs` patterns.
55
+reference before it is matched against `transfer.hiderefs` patterns. In
56
+order to match refs before stripping, add a `^` in front of the ref name. If
57
+you combine `!` and `^`, `!` must be specified first.
58
++
59
For example, if `refs/heads/master` is specified in `transfer.hideRefs` and
60
the current namespace is `foo`, then `refs/namespaces/foo/refs/heads/master`
58
-is omitted from the advertisements but `refs/heads/master` and
59
-`refs/namespaces/bar/refs/heads/master` are still advertised as so-called
60
-"have" lines. In order to match refs before stripping, add a `^` in front of
61
-the ref name. If you combine `!` and `^`, `!` must be specified first.
61
+is omitted from the advertisements. If `uploadpack.allowRefInWant` is set,
62
+`upload-pack` will treat `want-ref refs/heads/master` in a protocol v2
63
+`fetch` command as if `refs/namespaces/foo/refs/heads/master` did not exist.
64
+`receive-pack`, on the other hand, will still advertise the object id the
65
+ref is pointing to without mentioning its name (a so-called ".have" line).
66
+
67
Even if you hide refs, a client may still be able to steal the target
68
objects via the techniques described in the "SECURITY" section of the