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>

diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc
index 455ce40be892de8dd7af43d9cb89e8c4c945cf83..f07a2e883bd96c2f972b3081b3a35dcd206ec5b9 100644 (file)
--- a/Documentation/config/promisor.adoc
+++ b/Documentation/config/promisor.adoc
@@ -32,24 +32,41 @@ variable is set to "true", and the "name" and "url" fields are always
 advertised regardless of this setting.
 
 promisor.acceptFromServer::
-       If set to "all", a client will accept all the promisor remotes
-       a server might advertise using the "promisor-remote"
-       capability. If set to "knownName" the client will accept
-       promisor remotes which are already configured on the client
-       and have the same name as those advertised by the client. This
-       is not very secure, but could be used in a corporate setup
-       where servers and clients are trusted to not switch name and
-       URLs. If set to "knownUrl", the client will accept promisor
-       remotes which have both the same name and the same URL
-       configured on the client as the name and URL advertised by the
-       server. This is more secure than "all" or "knownName", so it
-       should be used if possible instead of those options. Default
-       is "none", which means no promisor remote advertised by a
-       server will be accepted. By accepting a promisor remote, the
-       client agrees that the server might omit objects that are
-       lazily fetchable from this promisor remote from its responses
-       to "fetch" and "clone" requests from the client. Name and URL
-       comparisons are case sensitive. See linkgit:gitprotocol-v2[5].
+       Controls which promisor remotes advertised by a server (using the
+       "promisor-remote" protocol capability) a client will accept. By
+       accepting a promisor remote, the client agrees that the server
+       might omit objects that are lazily fetchable from this promisor
+       remote from its responses to "fetch" and "clone" requests.
++
+Note that this option does not cause new remotes to be automatically
+created in the client's configuration. It only allows remotes which
+are somehow already configured to be trusted for the current
+operation, or their fields to be updated (if `promisor.storeFields` is
+set and the remote already exists locally). To allow Git to
+automatically create and persist new remotes from server
+advertisements, use `promisor.acceptFromServerUrl`.
++
+The available options are:
++
+* `none` (default): No promisor remote advertised by a server will be
+  accepted.
++
+* `knownUrl`: The client will accept promisor remotes that are already
+  configured on the client and have both the same name and the same URL
+  as advertised by the server. This is more secure than `all` or
+  `knownName`, and should be used if possible instead of those options.
++
+* `knownName`: The client will accept promisor remotes that are already
+  configured on the client and have the same name as those advertised
+  by the server. This is not very secure, but could be used in a corporate
+  setup where servers and clients are trusted to not switch names and URLs.
++
+* `all`: The client will accept all the promisor remotes a server might
+  advertise. This is the least secure option and should only be used in
+  fully trusted environments.
++
+Name and URL comparisons are case-sensitive. See linkgit:gitprotocol-v2[5]
+for protocol details.
 
 promisor.acceptFromServerUrl::
        A glob pattern to specify which server-advertised URLs a