diff mbox series

[3/3] docs: clarify the interaction of transfer.hideRefs and namespaces

Message ID 20210809175530.75326-4-kim@eagain.st (mailing list archive)
State New
Headers show
Series upload-pack: treat want-ref relative to namespace | expand

Commit Message

Kim Altintop Aug. 9, 2021, 5:57 p.m. UTC
Expand the section about namespaces in the documentation of
`transfer.hideRefs` to point out the subtle differences between
`upload-pack` and `receive-pack`.

9bedd82017 (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 documented.

Signed-off-by: Kim Altintop <kim@eagain.st>
---
 Documentation/config/transfer.txt | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

--
2.32.0

Comments

Kim Altintop Aug. 10, 2021, 9:49 a.m. UTC | #1
> diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt
> index 505126a780..09ebb399ce 100644
> --- a/Documentation/config/transfer.txt
> +++ b/Documentation/config/transfer.txt
> @@ -52,13 +52,16 @@ If you have multiple hideRefs values, later entries override earlier ones
>  (and entries in more-specific config files override less-specific ones).
>  +
>  If a namespace is in use, the namespace prefix is stripped from each
> -reference before it is matched against `transfer.hiderefs` patterns.
> -For example, if `refs/heads/master` is specified in `transfer.hideRefs` and
> -the current namespace is `foo`, then `refs/namespaces/foo/refs/heads/master`
> -is omitted from the advertisements but `refs/heads/master` and
> -`refs/namespaces/bar/refs/heads/master` are still advertised as so-called
> -"have" lines. In order to match refs before stripping, add a `^` in front of
> -the ref name. If you combine `!` and `^`, `!` must be specified first.
> +reference before it is matched against `transfer.hiderefs` patterns. For
> +example, if `refs/heads/master` is specified in `transfer.hideRefs` and the
> +current namespace is `foo`, then `refs/namespaces/foo/refs/heads/master` is
> +omitted from the advertisements. If `uploadpack.allowRefInWant` is set,
> +`upload-pack` will treat `want-ref refs/heads/master` in a protocol v2
> +`fetch` command as if `refs/heads/master` was unknown. Note, however, that
> +`receive-pack` will still advertise the object id `refs/heads/master` is
> +pointing to, but will conceil the name of the ref. In order to match refs
> +before stripping, add a `^` in front of the ref name. If you combine `!` and
> +`^`, `!` must be specified first.
>  +
>  Even if you hide refs, a client may still be able to steal the target
>  objects via the techniques described in the "SECURITY" section of the

I'd appreciate some feedback on this one before rerolling. Having looked at the
code many times recently, it makes sense to me, but that could be different for
someone with less fresh memory. Thanks!
diff mbox series

Patch

diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt
index 505126a780..09ebb399ce 100644
--- a/Documentation/config/transfer.txt
+++ b/Documentation/config/transfer.txt
@@ -52,13 +52,16 @@  If you have multiple hideRefs values, later entries override earlier ones
 (and entries in more-specific config files override less-specific ones).
 +
 If a namespace is in use, the namespace prefix is stripped from each
-reference before it is matched against `transfer.hiderefs` patterns.
-For example, if `refs/heads/master` is specified in `transfer.hideRefs` and
-the current namespace is `foo`, then `refs/namespaces/foo/refs/heads/master`
-is omitted from the advertisements but `refs/heads/master` and
-`refs/namespaces/bar/refs/heads/master` are still advertised as so-called
-"have" lines. In order to match refs before stripping, add a `^` in front of
-the ref name. If you combine `!` and `^`, `!` must be specified first.
+reference before it is matched against `transfer.hiderefs` patterns. For
+example, if `refs/heads/master` is specified in `transfer.hideRefs` and the
+current namespace is `foo`, then `refs/namespaces/foo/refs/heads/master` is
+omitted from the advertisements. If `uploadpack.allowRefInWant` is set,
+`upload-pack` will treat `want-ref refs/heads/master` in a protocol v2
+`fetch` command as if `refs/heads/master` was unknown. Note, however, that
+`receive-pack` will still advertise the object id `refs/heads/master` is
+pointing to, but will conceil the name of the ref. In order to match refs
+before stripping, add a `^` in front of the ref name. If you combine `!` and
+`^`, `!` must be specified first.
 +
 Even if you hide refs, a client may still be able to steal the target
 objects via the techniques described in the "SECURITY" section of the