doc: promisor: improve acceptFromServer entry
The entry for the `promisor.acceptFromServer` in "Documentation/config/promisor.adoc" has a number of issues: - it's not clear if new remotes and URLs can be created, - it looks like a big block of text, - it's not easy to see all the options, - it's not easy to see which option is the default one, - for "knownName", it says "advertised by the client" instead of "advertised by the server", - it doesn't refer to the new related `acceptFromServerUrl` option. Let's address all these issues by rewording large parts of it and using bullet points for the different options. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Christian Couder committed
May 27, 2026 at 16:08 UTC
8f32e6f343b451f04e57dfda31bef04cb23f65a1
1 file changed
+35
-18
Documentation/config/promisor.adoc
+35
-18
@@ -32,24 +32,41 @@ variable is set to "true", and the "name" and "url" fields are always
32
advertised regardless of this setting.
33
34
promisor.acceptFromServer::
35
- If set to "all", a client will accept all the promisor remotes
36
- a server might advertise using the "promisor-remote"
37
- capability. If set to "knownName" the client will accept
38
- promisor remotes which are already configured on the client
39
- and have the same name as those advertised by the client. This
40
- is not very secure, but could be used in a corporate setup
41
- where servers and clients are trusted to not switch name and
42
- URLs. If set to "knownUrl", the client will accept promisor
43
- remotes which have both the same name and the same URL
44
- configured on the client as the name and URL advertised by the
45
- server. This is more secure than "all" or "knownName", so it
46
- should be used if possible instead of those options. Default
47
- is "none", which means no promisor remote advertised by a
48
- server will be accepted. By accepting a promisor remote, the
49
- client agrees that the server might omit objects that are
50
- lazily fetchable from this promisor remote from its responses
51
- to "fetch" and "clone" requests from the client. Name and URL
52
- comparisons are case sensitive. See linkgit:gitprotocol-v2[5].
35
+ Controls which promisor remotes advertised by a server (using the
36
+ "promisor-remote" protocol capability) a client will accept. By
37
+ accepting a promisor remote, the client agrees that the server
38
+ might omit objects that are lazily fetchable from this promisor
39
+ remote from its responses to "fetch" and "clone" requests.
40
++
41
+Note that this option does not cause new remotes to be automatically
42
+created in the client's configuration. It only allows remotes which
43
+are somehow already configured to be trusted for the current
44
+operation, or their fields to be updated (if `promisor.storeFields` is
45
+set and the remote already exists locally). To allow Git to
46
+automatically create and persist new remotes from server
47
+advertisements, use `promisor.acceptFromServerUrl`.
48
++
49
+The available options are:
50
++
51
+* `none` (default): No promisor remote advertised by a server will be
52
+ accepted.
53
++
54
+* `knownUrl`: The client will accept promisor remotes that are already
55
+ configured on the client and have both the same name and the same URL
56
+ as advertised by the server. This is more secure than `all` or
57
+ `knownName`, and should be used if possible instead of those options.
58
++
59
+* `knownName`: The client will accept promisor remotes that are already
60
+ configured on the client and have the same name as those advertised
61
+ by the server. This is not very secure, but could be used in a corporate
62
+ setup where servers and clients are trusted to not switch names and URLs.
63
++
64
+* `all`: The client will accept all the promisor remotes a server might
65
+ advertise. This is the least secure option and should only be used in
66
+ fully trusted environments.
67
++
68
+Name and URL comparisons are case-sensitive. See linkgit:gitprotocol-v2[5]
69
+for protocol details.
70
71
promisor.acceptFromServerUrl::
72
A glob pattern to specify which server-advertised URLs a